Running a pre 2024.10 ORIGAM Server in Docker Locally

This guide will walk you through the process of running official pre 2024.10 Origam docker images on your local machine for development or testing purposes.

If you want to run the image 2024.10 or later look at this guide.

Prerequisites

  • Docker installed on your system
  • Basic knowledge of command-line operations

We’ll be using the test model included in the Origam repository for this demonstration. This guide assumes you’re working in the directory C:\test\docker, but feel free to adjust the paths as needed for your setup.

Steps

  1. Generate SSL Certificate
  2. Create Environment File
  3. Create Nginx Configuration File
  4. Run Docker Container

1. Generate SSL Certificate

First, we need to create an SSL certificate for Nginx. This is necessary because Origam image would not work correctly without it.

If you have Git installed, you can use the OpenSSL located in the Git install directory (C:\Program Files\Git\mingw64\bin\openssl.exe). Otherwise, you’ll need to install OpenSSL separately.

Run the following commands in your command prompt or PowerShell:

openssl genrsa -out server.key 2048

openssl req -new -key server.key -out server.csr

openssl x509 -req -days 365 -in server.csr -signkey server.key -out server.crt

These commands generate a private key, a certificate signing request, and a self-signed certificate valid for 365 days.

2. Create Environment File

Create a new file named demo.env in your working directory (C:\test\docker) with the following content:

OrigamSettings_SetOnStart=true
OrigamSettings_SchemaExtensionGuid=f17329d6-3143-420a-a2e6-30e431eea51d
OrigamSettings_DbHost={ip address of your db}
OrigamSettings_DbPort=1433
OrigamSettings_DbUsername={your db user}
OrigamSettings_DbPassword={your db password}
DatabaseName=origam-demo
DatabaseType=mssql
ExternalDomain_SetOnStart=https://localhost
TZ=Europe/Prague

Replace the placeholders {ip address of your db}, {your db user}, and {your db password} with your actual database details. If your database runs on your local machine set OrigamSettings_DbHost=host.docker.internal. You can also change the time zone the container will be running in by changing TZ=Europe/Prague.

Note: If you’re using a different model than the test model, you’ll need to change OrigamSettings_SchemaExtensionGuid (package ID of the main package in your model), DatabaseName, and OrigamSettings_ModelName accordingly.

3. Create Nginx Configuration File

Create another file named nginx.conf in your working directory with the following content:

user www-data;
worker_processes auto;
pid /run/nginx.pid;
include /etc/nginx/modules-enabled/*.conf;

events {
    worker_connections 768;
}

http {
    sendfile on;
    tcp_nopush on;
    types_hash_max_size 2048;
    include /etc/nginx/mime.types;
    default_type application/octet-stream;

    ssl_protocols TLSv1.2 TLSv1.3;
    ssl_prefer_server_ciphers on;
    ssl_ciphers ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384:ECDHE-ECDSA-CHACHA20-POLY1305:ECDHE-RSA-CHACHA20-POLY1305:DHE-RSA-AES128-GCM-SHA256:DHE-RSA-AES256-GCM-SHA384;

    access_log /var/log/nginx/access.log;
    error_log /var/log/nginx/error.log;

    gzip on;

    server {
        listen 443 ssl;
        server_name localhost;
        ssl_certificate /etc/nginx/ssl/server.crt;
        ssl_certificate_key /etc/nginx/ssl/server.key;

        location / {
            proxy_pass http://localhost:8080;
            proxy_set_header Host $host;
            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;
        }
    }

    include /etc/nginx/conf.d/*.conf;
    include /etc/nginx/sites-enabled/*;
}

This configuration sets up Nginx to use SSL and proxy requests to the Origam application.

4. Run Docker Container

Now you can run the Docker image with this command (adjust paths as necessary):

docker run --env-file C:\test\docker\demo.env ^
    -it --name OrigamDemo ^
    -v {path to test model}\model-tests\model:/home/origam/HTML5/data/origam ^
    -v C:\test\docker\server.crt:/etc/nginx/ssl/server.crt:ro ^
    -v C:\test\docker\server.key:/etc/nginx/ssl/server.key:ro ^
    -v C:\test\docker\nginx.conf:/etc/nginx/nginx.conf:ro ^
    -p 443:443 ^
    origam/server:master-latest.linux

Replace {path to test model} with the actual path to the test model on your system.

This command does the following:

  • Uses the environment file we created
  • Names the container “OrigamDemo”
  • Mounts the test model, SSL certificate, key, and Nginx configuration into the container
  • Maps port 443 from the container to your host machine
  • Uses the latest Origam server image for Linux

Accessing the Application

After running the Docker command, wait for the container to start up. Once it’s ready, you can access the Origam application by opening https://localhost in your web browser.

Note: Since we’re using a self-signed certificate, you may see a security warning in your browser. This is expected and you can proceed safely for development purposes.

Troubleshooting

  • If you encounter issues with the database connection, double-check your database details in the demo.env file.
  • Make sure all paths in the Docker run command are correct and the files exist.
  • If you’re unable to access the application, ensure no other service is using port 443 on your machine.

Notes

Form more details on the docker image, enviromnetal variables and configuration look here.

Couldn’t we include the certificate generation in the image? For development purposes. It is quite an extra step the developer has to do otherwise.

We could. We could change the startup.cs code to make it easier to change the port too. May be we could change the nginx config so that it works out of the box. But this is not how it is used in production I hear. So I’m not sure if there could be some negative impacts.

That is why I wrote “for development purposes”.