Skip to main content

Docker Compose [Recommended]

Docker Compose is the recommended method to run OpenLift in production. Below are the steps to deploy OpenLift using Docker Compose.

Step 1 - Create the required files​

Create a directory of your choice (e.g., ./openlift-app) to hold the docker-compose.yml and .env files.

Move to the directory you created
mkdir ./openlift-app
cd ./openlift-app

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

docker-compose.yml

version: '3.8'

services:
openlift-db:
  image: postgres:15
  container_name: openlift-db
  environment:
    POSTGRES_DB: openlift
    POSTGRES_USER: openlift_user
    POSTGRES_PASSWORD: openlift_password
  volumes:
    - ./data/postgres:/var/lib/postgresql/data
  ports:
    - "5432:5432"

openlift-service:
  image: openlift-service:latest
  container_name: openlift-service
  environment:
    DATABASE_URL: ${DATABASE_URL}
    JWT_SECRET: ${JWT_SECRET}
    COOKIE_SECRET: ${COOKIE_SECRET}
    CORS_ORIGIN: ${CORS_ORIGIN}
    PORT: ${PORT}
  ports:
    - "4000:4000"
  depends_on:
    - openlift-db

openlift-app:
  image: openlift-app:latest
  container_name: openlift-app
  environment:
    VITE_BACKEND_BASE_URL: ${VITE_BACKEND_BASE_URL}
  ports:
    - "3000:3000"
  depends_on:
    - openlift-service

Step 2 - Populate the .env file​

Create a .env file in the same directory. Below is an example .env file with the minimum required configuration:

Example .env file

VITE_BACKEND_BASE_URL=http://localhost:4000
DATABASE_URL=postgresql://openlift_user:openlift_password@openlift-db:5432/openlift
JWT_SECRET=your-jwt-secret
COOKIE_SECRET=your-cookie-secret
CORS_ORIGIN=*
PORT=4000
LOCAL_STORAGE_PATH=./data

Explanation:​

  • VITE_BACKEND_BASE_URL – The URL where the backend service is running.
  • DATABASE_URL – Connection string for the PostgreSQL database.
  • JWT_SECRET – Secret key used for signing JSON Web Tokens.
  • COOKIE_SECRET – Secret key used for signing cookies.
  • CORS_ORIGIN – Allowed origins for CORS requests.
  • PORT – Port where the backend service will run.
  • LOCAL_STORAGE_PATH – Path for local storage files.

Step 3 - Start the containers​

From the directory you created in Step 1 (which should now contain your docker-compose.yml and .env files), run the following commands:

1. Pull the latest container images:​

Pull the latest images
docker compose pull

2. Create the containers:​

Create the containers
docker compose create

3. Start the containers:​

Start the containers
docker compose up -d

The -d option runs the containers in detached mode (in the background).

4. Check container health:​

Ensure that all containers are running and healthy:

Check container health
docker ps

Troubleshooting​

Docker version

If you get an error such as unknown shorthand flag: 'd' in -d or open <location of your .env file>: permission denied, you are probably running the wrong Docker version.

You can correct the problem by following the complete Docker Engine install procedure for your distribution, including the "Uninstall old versions" and "Install using the apt/rpm repository" sections.

Health check start interval

If you get an error can't set healthcheck.start_interval as feature require Docker Engine v25 or later, it helps to comment out the line for start_interval in the database section of the docker-compose.yml file.

Next Steps​

Once the containers are running, the backend will be available at http://localhost:4000 and the frontend at http://localhost:3000.

Setting up optional features:​

  • External Storage – Configure an external volume to store user-uploaded images and backups.
  • Reverse Proxy – Set up NGINX Proxy Manager or Traefik to expose your app to the internet securely.
  • HTTPS – Use Let's Encrypt to secure the connection with SSL/TLS.

Upgrading​

To update the OpenLift containers to the latest version, run the following commands:

Upgrade and restart OpenLift
docker compose pull && docker compose up -d

To clean up disk space, the old version's unused container images can be deleted with:

Clean up unused Docker images
docker image prune

Additional Resources:​