Running ORIGAM Server in Docker Locally

jsusen · February 26, 2025, 8:19am

Running ORIGAM Server in Docker Locally

This guide will walk you through the process of running official ORIGAM docker images of version 2025.3 and later on your local machine for development or testing purposes.

If you want to build and run your own image from ORIGAM source folow this guide.

If you want to run an image earlier than 2025.3 look at this guide.

If you want to run an image earlier than 2024.10 look at this guide.

Prerequisites

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

You will also need an ORIGAM project (model) to run on the server. If you don’t have one yet and just want to try things out you can use the test model included in the ORIGAM repository. This guide assumes you’re working in the directory C\Origam\MyProject\Docker, but feel free to adjust the paths as needed for your setup.

Steps

Create Environment File
Run Docker Container

1. Create Environment File

Create a new file named demo.env in your working directory (for example C:\Origam\MyProject\Docker) with the following content:

OrigamSettings__DefaultSchemaExtensionId={main package id}
OrigamSettings__DatabaseHost={ip address of your db}
OrigamSettings__DatabasePort=1433
OrigamSettings__DatabaseUsername={your db user}
OrigamSettings__DatabasePassword={your db password}
OrigamSettings__Name={your project name}
OrigamSettings__DatabaseName={your db name}
CustomAssetsConfig__PathToCustomAssetsFolder=/home/origam/projectData/customAssets
CustomAssetsConfig__RouteToCustomAssetsFolder=/customAssets
DatabaseType=mssql
ExternalDomain_SetOnStart=https://localhost
TZ=Europe/Prague

Then replace the placeholders

{ip address of your db}: Your database’s IP address. For a local database, use host.docker.internal
{your db name}: Name of your new database (preferably your project’s name)
{your db user}: Your database username
{your db password}: Your database password
{main package id}: ID of your project’s main package. I you use the test model, the id is: f17329d6-3143-420a-a2e6-30e431eea51d
CustomAssetsConfig__PathToCustomAssetsFolder is the path in the docker image where the custom assests folder will be mounted. The folder should cointain custom action icons for example.
CustomAssetsConfig__RouteToCustomAssetsFolder is the route where the the client application can find the custom assets.

Additional configuration

Create a new database with the name you specified in {your db name}
Adjust the time zone if needed by changing TZ=Europe/Prague

2. 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 {your project name} ^
    -v {path to the model}:/home/origam/projectData/model ^
    -v {path to the assets folder}:/home/origam/projectData/customAssets ^
    -p 443:443 ^
    origam/server:master-latest.linux

Replace the placeholders

{your project name}: Your project’s name (no spaces)
{path to the model}: Path to the model directory of your project. If you use the test model and you cloned it here for example: C:\Repos\origam the the model path would be C:\Repos\origam\model-tests\model
{path to the assets folder} this shouldcorrespond to the CustomAssetsConfig__PathToCustomAssetsFolder defined in the env file.

The above command will do the following:

Uses the environment file we created
Maps port 443 from the container to your host machine
Uses the latest ORIGAM server image for Linux
Creates and starts a new Docker container with that image

Note: If you want the container to run with your own SSL certificate and not the autogenerated development one, you can add this to the docker run command.

 -v C:\test\docker\server.crt:/etc/nginx/ssl/server.crt:ro ^
 -v C:\test\docker\server.key:/etc/nginx/ssl/server.key:ro ^

Look here for more details.

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.

Windows Containers

you can run the windows containers like this

docker run --env-file C:\test\docker\demo.env ^
    -it --name {your project name}  ^
    -v {path to the model}:/home/origam/projectData/model ^
    -v {path to the assets folder}:/home/origam/projectData/customAssets ^
    -p 443:443 ^
    origam/server:master-latest.win

If you want to add your own SSL certificate you wil need a https.pfx file with the certificate and a https-cert-password.txt which is a plain text file with the cetrificate password. You can create the https.pfx file with these commands if you want to try this out.

openssl req -new -newkey rsa:2048 -nodes -keyout https.key -out https.csr -subj "/C=US/ST=State/L=City/O=Organization/OU=OrganizationalUnit/CN=localhost"
openssl x509 -req -days 365 -in https.csr -signkey https.key -out https.crt
openssl pkcs12 -export -out https.pfx -inkey https.key -in https.crt -password pass:yourPassword

Then create the https-cert-password.txt file and put yourPassword inside.
Then you can run the container like this.

docker run --env-file C:/Bordel/docker/demo.env ^
    -it --name {your project name}  ^
    -v {directory with the certificate files}:C:/ssl ^
    -v {path to the model}:C:\home\origam\HTML5\data\origam ^
    -p 443:443 ^
    origam/server:master-latest.win

This will mount {directory with the certificate files} into the C:/ssl directory in the container.

Notes

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