Standalone - Virtual Machine Linux Backend server installation

Support DQE
Support DQE
  • Updated

1. Architecture

Once your dedicated DQE One Standalone server instance is up and running, you can launch and expose the backend application from your virtual machine.

This document describes an example configuration to set up the Standalone backend server instance on an Ubuntu virtual machine. This document does not cover the full security layer of your own environment.

The backend application is deployed with Docker Compose and is usually exposed through NGINX over HTTPS.

Internet
   |
HTTPS:443
   |
NGINX
   |
http://127.0.0.1:8000
   |
DQE One Standalone backend

Security measures

  • Protocols and ports: expose the application publicly through HTTPS on port 443. The Docker application itself listens on port 8000 and should preferably remain behind NGINX.
  • IP filtering: depending on your architecture, restrict inbound access to trusted IP addresses only.
  • SSL certificate: if the VM is directly exposed to the internet, it must have a DNS entry and an associated SSL certificate.

Recommendation

  • Server configuration:
    • Type: Unix, for example Ubuntu
    • RAM: 3 to 5 GB
    • Disk space: 10 GB minimum
    • CPU: 1 vCPU minimum

2. Installation

2.1. Prerequisites

Docker installation

$ sudo apt update
$ sudo apt install apt-transport-https ca-certificates curl software-properties-common
$ curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo apt-key add -
$ sudo add-apt-repository "deb [arch=amd64] https://download.docker.com/linux/ubuntu focal stable"
$ sudo apt update
$ sudo apt install docker-ce
$ docker --version

Note: on recent Ubuntu versions, the apt-key command may display a deprecation warning. This warning is expected and does not prevent Docker from being installed if the command returns OK.

Docker Compose

Recent Docker versions include Docker Compose V2 by default. This guide uses the Compose plugin command:

$ docker compose

Verify that Docker Compose is available:

$ docker compose version

If a version number is returned, no additional Docker Compose installation is required.

NGINX installation

$ sudo apt update
$ sudo apt install nginx

Configuration example:

server {
    listen 443 ssl;
    server_name myserver.example.com;

    ssl_certificate /etc/nginx/ssl/[MY_CERTIFICATE].pem;
    ssl_certificate_key /etc/nginx/ssl/[MY_PRIVATE_KEY].key;

    ssl_protocols TLSv1.2 TLSv1.3;

    location / {
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_set_header Host $host;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "Upgrade";
        proxy_http_version 1.1;
        proxy_set_header X-Forwarded-Host $host;
        proxy_set_header X-Forwarded-Server $host;
        proxy_set_header Cookie $http_cookie;
        proxy_set_header Referer $http_referer;

        proxy_pass http://127.0.0.1:8000;
    }

    access_log /var/log/nginx/dqeone-standalone.log;
    error_log /var/log/nginx/dqeone-standalone-error.log error;
}

After updating the NGINX configuration, restart NGINX:

$ sudo systemctl restart nginx

2.2. Docker Compose file

Create a docker-compose.yml file with the following content:

services:

  redis:
    container_name: redis
    image: dqeone.azurecr.io/dqe-one-redis:v1.0
    hostname: redis
    logging:
      driver: none
    ports:
      - "6379:6379"
    volumes:
      - redis_data:/data

  rabbitmq:
    image: dqeone.azurecr.io/dqe-one-rabbitmq:v1.0
    container_name: rabbitmq
    hostname: rabbitmq
    logging:
      driver: none
    depends_on:
      - redis
    environment:
      RABBITMQ_DEFAULT_PASS: guest
      RABBITMQ_DEFAULT_USER: guest
      RABBITMQ_DEFAULT_VHOST: admin
    volumes:
      - rabbitmq_data:/var/lib/rabbitmq/
      - rabbitmq_log:/var/log/rabbitmq/
    ports:
      - "15672:15672"

  dqeone:
    container_name: dqeone
    image: dqeone.azurecr.io/standalone:v1.4.0
    hostname: dqeone
    expose:
      - "8000"
    ports:
      - "8000:8000"
    depends_on:
      - redis
      - rabbitmq
      - postgres
    environment:
      - SFAPIVERSION=v65.0
      - CREATE_SUPERUSER=true
      - RUN_COLLECTSTATIC=false
      - DQE_ONE_SERVER_ADMIN_USER=<admin_user>
      - DQE_ONE_SERVER_ADMIN_PASSWORD=<admin_password>
      - DQE_CLIENT_LICENCE=<client_licence>
      - WEBSITE_HOSTNAME=https://<your-domain>
      - SECRET_ENCRYPTION_KEY=<secret_encryption_key>
      - WAIT_HOSTS=redis:6379
      - WAIT_HOSTS_TIMEOUT=300
      - WAIT_SLEEP_INTERVAL=5
      - WAIT_HOST_CONNECT_TIMEOUT=30
      - REDIS_URL=redis://redis:6379
      - PORT=8000
      - DEBUG=false
      - DB_USER=dqeone
      - DB_PASSWORD=<database_password>
      - DB_NAME=dqeone
      - DB_HOST=postgres
      - DB_VOLUME_PATH=./db/
      - DB_MAX_CAPACITY=8000000000
      - AUTHORIZED_SFTP_HOSTS=<authorized_sftp_hosts>
    command:
      - "bash"
      - "./entrypoint.sh"

  postgres:
    container_name: postgres
    image: dqeone.azurecr.io/dqe-one-postgres:v1.0
    logging:
      driver: none
    environment:
      POSTGRES_USER: dqeone
      POSTGRES_PASSWORD: <database_password>
      POSTGRES_DB: dqeone
    expose:
      - "5432"
    ports:
      - "5432:5432"
    volumes:
      - postgres_data:/var/lib/postgresql/data

volumes:
  rabbitmq_data:
  rabbitmq_log:
  redis_data:
  postgres_data:

Important: replace all placeholder values between <...> with the values provided or generated for the customer installation.

Important: use the image versions provided by DQE. Do not replace them with the latest tag, as some images may not be published with this tag.

Security note: do not publish real customer credentials, licence keys, encryption keys, registry passwords, or database passwords in the documentation.

Environment variables

The dqeone service requires several environment variables to configure the Standalone backend.

Variable Example value Description
SFAPIVERSION v65.0 Salesforce API version used by the application when communicating with Salesforce.
CREATE_SUPERUSER true Creates the initial administrator account during the first startup.
RUN_COLLECTSTATIC false Executes the Django collectstatic command during startup. Set to false unless explicitly required.
DQE_ONE_SERVER_ADMIN_USER <admin_user> Username of the initial administrator account.
DQE_ONE_SERVER_ADMIN_PASSWORD <admin_password> Password of the initial administrator account. Choose a strong password and keep it confidential.
DQE_CLIENT_LICENCE <client_licence> Customer licence key provided by DQE.
WEBSITE_HOSTNAME https://standalone.example.com Public HTTPS URL of the Standalone instance. This value must match the DNS name and NGINX configuration.
SECRET_ENCRYPTION_KEY <secret_encryption_key> Secret key used to encrypt sensitive information stored by the application. Generate a unique key for each installation and never change it after deployment.
WAIT_HOSTS redis:6379 List of dependent services that must be reachable before the application starts.
WAIT_HOSTS_TIMEOUT 300 Maximum waiting time, in seconds, for dependent services to become available.
WAIT_SLEEP_INTERVAL 5 Delay, in seconds, between two availability checks.
WAIT_HOST_CONNECT_TIMEOUT 30 Timeout, in seconds, for each connection attempt to a dependent service.
REDIS_URL redis://redis:6379 Redis connection URL used by the application.
PORT 8000 Internal listening port of the application.
DEBUG false Enables or disables debug mode. This value must be set to false in production.
DB_USER dqeone PostgreSQL database username used by the application.
DB_PASSWORD <database_password> PostgreSQL database password used by the application. It must match POSTGRES_PASSWORD in the postgres service.
DB_NAME dqeone PostgreSQL database name used by the application. It must match POSTGRES_DB in the postgres service.
DB_HOST postgres Hostname of the PostgreSQL service defined in the Docker Compose file.
DB_VOLUME_PATH ./db/ Path used by the application for database-related storage.
DB_MAX_CAPACITY 8000000000 Maximum database capacity, expressed in bytes.
AUTHORIZED_SFTP_HOSTS depot-1.dqe-software.net Comma-separated list of SFTP hosts authorized by the application for secure file exchanges.

Important: the SECRET_ENCRYPTION_KEY must be generated once and kept for the lifetime of the deployment. Changing this value after the application has been initialized may prevent previously encrypted data from being decrypted.

To generate a compatible encryption key, run:

python3 -c "from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())"

If the cryptography module is not installed, install it first: 

sudo apt install python3-cryptography

2.3. Validate the Docker Compose file

$ docker compose config

If Docker Compose returns an error such as:

yaml: found character that cannot start any token

check the indentation of the file. YAML only supports spaces. Tabs or invisible characters may generate this error. The issue may also be located on the line before the one indicated in the error message.

3. Launcher

3.1. Connecting to the DQE Azure Container Registry

$ docker login dqeone.azurecr.io
Username: <Login provided by DQE>
Password: <Password provided by DQE>

3.2. Download the images

$ docker compose pull

If Docker returns an unauthorized error while pulling an image, verify that all images use the Azure Container Registry provided by DQE. Customer installations should not reference development registries such as dqeonedev.azurecr.io.

3.3. Start the services

$ docker compose up -d

Verify that every container is running:

$ docker compose ps

Expected services:

  • dqeone
  • redis
  • rabbitmq
  • postgres

3.4. Verify the installation

$ curl -I http://localhost:8000

A response similar to the following confirms that the application is running: 

HTTP/1.1 301 Moved Permanently

Once NGINX is configured, the application should be accessible through the public HTTPS endpoint: 

https://<your-domain>

4. Troubleshooting

YAML parsing error

yaml: found character that cannot start any token

Possible causes:

  • Tab character
  • Invalid indentation
  • Invisible character

Solution:

  • Replace tabs with spaces.
  • Validate the file using docker compose config.
  • Check the line before the one indicated by the error message.

Unauthorized while pulling images

unauthorized: authentication required

Verify that:

  • you successfully authenticated using docker login dqeone.azurecr.io;
  • all images reference the DQE production registry dqeone.azurecr.io;
  • the image versions match those provided by DQE.

Cannot access the application remotely

Verify that:

  • the Docker containers are running;
  • NGINX is running;
  • port 443 is allowed by the server firewall;
  • the SSL certificate is correctly configured;
  • the DNS entry points to the VM or gateway exposing the service.

Related to

Was this article helpful?

0 out of 0 found this helpful