Installation

1. Register an account on SaaS platform or set up a Container registry on your server.

For more details about Container registry, see the Container registry section.

2. Download the latest stable release of ABCD Lite and place it in the target directory (e.g., C:\services\abcd-lite).

Create a directory on the server where the executable and configuration files, as well as the application's internal database, will be located. Although for the Windows ecosystem, preferred paths are ProgramFiles, AppData, and others, we recommend using a separate directory for such services. This is primarily related to the convenience of server usage and maintenance.

We will use the directory C:\services\abcd-lite as an example.

The latest stable release of ABCD Lite can be downloaded from the GitHub repository in the Releases section, or by following this link: https://github.com/1k-off/abcd-lite/releases/latest/download/abcd-lite-windows-amd64.tar.gz.

After downloading, extract the executable file abcd-lite.exe and place it in the installation directory.

3. Initialization

For initialization, you need to create basic configuration files for ABCD Lite and IIS. IIS will act as a reverse proxy and SSL terminator to avoid opening additional ports on the server and not bother security auditors unnecessarily.

Open PowerShell terminal in the directory with the executable file (e.g., C:\services\abcd-lite) and perform basic application configuration by running the following command:

./abcd-lite.exe config generate

As a result of executing this command, basic configuration files for the program (configs/config.yml) and web server (web/web.config) will be created, as well as an administrative password for accessing the web management interface. Save the generated password in a secure location. It is displayed only once at this stage, and you will not be able to see it later. If you lose this password, it can be recovered using the command line. For more details about recovering the administrative password, see the Configuration Options section.

Warning

This command by default generates IIS configuration that allows external access to the administrative interface, which may seem unsafe to some users. To create a more secure configuration that will prohibit external access to the web interface and allow access only to necessary functions, use the command with the paranoid flag and add the corresponding entry to the hosts file on the server.

./abcd-lite.exe config generate --paranoid

Add the folowing to C:\Windows\System32\drivers\etc\hosts:

127.0.0.1 abcd.acme.com

In this case, access to the administrative interface using the domain will be allowed only from the local server, unless the user additionally opens the port that ABCD Lite uses.

4. Create a new IIS site.

If you need to deploy IIS sites, you probably know how to add another one :) Nevertheless, a brief description is provided below.

The IIS site is needed for communication between the external world and ABCD Lite. For example, for communication between CI systems and the deployment system. In any case, both the default configuration and paranoid configuration open the necessary endpoints to the world. Therefore, it's important to add an SSL certificate to the domain being used so that all data is transmitted in encrypted form. And generally - come on, sites without SSL shouldn't exist at all nowadays.

You will also need appropriate IIS modules for the application to work correctly. For more details about them, see the IIS Modules section.

When creating the site, you need to specify the following parameters:

  • Site name and host name: abcd.acme.com
  • Physical path: C:\services\abcd-lite\web
  • After adding the site, add HTTPS binding and certificate. You can use WinACME for this if you don't have existing one.

iis-website-create

5. Add your domain to the allowed_origins section of the configuration file.

The application uses a CORS mechanism that allows servers to specify who can access its resources and how. For more details about CORS, see https://developer.mozilla.org/en-US/docs/Web/HTTP/Guides/CORS.

So, for the application to work correctly and be accessible, you need to add the domain through which access to the application is provided to the app.allowed_origins section of the configuration file. You can either leave or remove existing values, however, it's recommended to keep the value http://localhost:{{app-port}} for emergency direct access to the administrative interface in case of incorrect IIS operation.

app:
  allowed_origins:
    - https://abcd.acme.com
    - http://localhost:8900

6. Verify functionality

This is an optional but quite important step that allows you to ensure everything works as it should and no errors were made during the previous steps.

Run the executable manually using the command .\abcd-lite.exe run and navigate to the newly created site in your browser. Enter the admin password, check the console, and ensure there are no errors. Stop the file execution with Ctrl + C.

7. Creating a Windows service

For continuous operation of ABCD Lite and automatic startup, it's recommended to create a Windows service. Unfortunately, the only way to do this currently is to use a third-party program for managing Windows services - NSSM, which can be downloaded at: https://nssm.cc/download.

To use NSSM, run the utility from the terminal using the following command (make sure nssm.exe is available in PATH):

nssm install ABCDLite

Then, in the program interface, fill in the necessary fields.

Application:

  • Path - path to the executable file. Example: C:\services\abcd-lite\abcd-lite.exe
  • Startup directory - path to the service root directory. Example: C:\services\abcd-lite
  • Arguments - program startup arguments. Set to run.
  • Service name - system service name. Should be without spaces. Set to ABCDLite.

Details:

  • Display name - display name of the service. Example: ABCD Lite.
  • Description - display description of the service. Example: ABCD Lite IIS deployment service.
  • Startup type - autostart type. Set to Automatic.

I/O:

  • Output (stdout) - path to the log file that will be written from the program's standard output stream. Set to C:\services\abcd-lite\logs\abcd-lite.log.
  • Error (stderr) - path to the log file that will be written from the program's standard error stream. Set to C:\services\abcd-lite\logs\abcd-lite.log.

nssm-1

nssm-2

nssm-3

8. Start the service.

You can do this either from the Windows Services menu or using nssm (command nssm start ABCDLite).

After starting the service, it's recommended to go to the administrative interface site and verify its functionality.