Debug mode

What is the Debug Mode?

App in Debug Mode can be hosted and debugged directly on your machine - in contrast to the standard mode, where the App is a part of the ArconQ platform runtime. However, it will be still connected to the ArconQ platform and leverage its system features, such as messaging, logging, and more.

Configuring the Debug Mode

In this section, you will find the step-by-step tutorial, that will guide you on how to prepare your app's codebase and ArconQ platform to use the Debug Mode.

Integrate your App with the ArconQ.SDK.Debug package

The first step to run your ArconQ App in Debug Mode is to download and use the ArconQ.SDK.Debug package:

1. Add to your project the ArconQ.SDK.Debug package from the Macrix public repository: https://nexus.macrix.eu/repository/arq-nuget/.
2. In your App's Program.cs file configure the Debug Mode as shown below:

tip

The ServerAddress property should be set to the ArconQ server's address (eg. arconq.prod) and you will find values to replace the ServerExposedPort, Password and AppAlias properties in the next steps in the ArconQ UI.

var builder = WebApplication.CreateBuilder(args);

// Example Debug Mode configuration
builder.Services.ConfigureDebugMode(builder.Configuration, config =>
{
    config.ServerAddress = "arconq.prod"; // provide your value!
    config.ServerExposedPort = 31667; // provide your value!
    config.Password = "3e394997-db6f-4c16-9e78-21b3788ad28c"; // provide your value!
    config.AppAlias = "your-arq-app-alias"; // provide your value!
});

// Additional ArconQ SDK configurations, as usual
builder.WebHost.ConfigureArconQ(builder.Configuration);
builder.Services.AddArconQ(builder.Configuration);

// ... your custom code such as services registration can be placed here

// ArconQ initialization, as usual
var app = builder.Build();
app.UsePublicApp(builder.Configuration).AddCustomUserInterface("swagger", "/swagger");
app.UseArconQ();
app.MapArconQ();

await app.RunAsync();

info

Ordering of the ArconQ extension methods is important! The ConfigureDebugMode has to be the first call after creating the web application builder.

caution

Pay attention to the configuration provided by some of the Visual Studio's default templates. Using app.MapFallbackToFile("any_parameter") or app.UseHttpsRedirection() will disrupt the Debug mode.

1. Build and push the App Template as you would do normally.

Create the App in ArconQ

To create an App in Debug Mode:

1. Initiate a new App creation with the App template created in the previous step as always.

2. Create an App port mapping for the application. This involves exposing a selected port outside the cluster and mapping it to the application port:

   
   • In the External Port field provide the port that will be used for the communication. The value must be between 30000 and 32767. Match the config.ServerExposedPort from the previous step with this value.
   • Set the App Port value to 2222 (the SSH port used under the hood).
   • Set the exposure type of app port mapping to Node Port.

note

In ArconQ versions before 1.2.0, the App Port was 22. Since 1.2.0, apps run as a non-root user and can no longer bind to the privileged port 22, so SSH listens on 2222 instead. If you are upgrading an existing Debug Mode app, update its App port mapping to use 2222 — see Migrating to ArconQ 1.2.0.

Enable Debug Mode and obtain the credentials

1. Edit your new App, check the Enable Debug Mode checkbox and save changes:

1. Go to the details of your new App in the ArconQ UI to obtain the required configuration values mentioned in the first step:

   
   • value under the Remote password property is the unique SSH password for the app and should be copied to the config.Password property in your code
   • value under the Alias property is the unique app identifier, that was set up during app creation and should be copied to the config.AppAlias property in your code

Debug Mode Workflow

This section describes how to connect your App to the ArconQ platform in Debug Mode and how to properly stop a debug session.

Connect your App in Debug Mode to the ArconQ platform

To connect your App in Debug Mode to ArconQ:

1. Initiate the App from the ArconQ platform. The status of the App should be initially Disconnected. This indicates that the ArconQ platform is waiting for the actual application to initiate the connection.
2. Start your App, which could be hosted anywhere outside the ArconQ Cluster.
3. Once your App is running, go back to the ArconQ UI. You should now see that the status of your App has changed to Connected, signifying a successful connection.

caution

Make sure that you don't have any service listening on the port 80 on the machine that you started your App (like the IIS).

Stopping a debug session

Your App is now running directly on your machine, which gives you the possibility to attach a debugger to it, but also control its lifecycle. Under the hood, your App connects with the App Proxy service, which fills the gap between your code and all of ArconQ's internal services. Because of the nature of debugging, where you can stop execution of code at any particular place using breakpoints, there is no possibility to reliably control the connection between your App and App Proxy using the standard ping <-> response pattern used in a normal ArconQ App lifecycle.

What the above means is that if you stop your App manually (whether it is sending SIGTERM signal, killing the app process or stopping the App in debugger), then the ArconQ is unaware of your App shutdown. This may lead to undesired behavior, such as scheduled job failures. Because of that the recommended way of stopping the debug session is to stop the App from ArconQ UI. That way, the ArconQ's App Proxy service will be stopped gracefully, and the shutdown signal will be sent to your App, stopping it in a graceful manner as well.