How to setup SimpleDMS locally with Docker Compose

In this how-to guide you learn how to install SimpleDMS locally with Docker Compose.

This is a step by step guide with just the absolute necessary background information. Visit the Setup Reference to get more in-depth knowledge more.

Prerequisites

• Working Docker setup.
• Mail account to send transactional mails, ideally a noreply address.
• (recommended) A TLS certificate to enable HTTPS. Not described in this guide.

This tutorial assumes you don't have S3 storage already.

Important notes

To keep this guide as easy to follow as possible, it does not explain setting up HTTPS, and file encryption is disabled.

I would recommend using HTTPS when running locally in a home lab too, but HTTPS can be setup in multiple ways and this guide cannot cover all of them. HTTPS is required if you want to use the PWA (progressive web app) on Android or iOS.

File encryption is disabled, because handling of the encryption key is not trivial and if the key or passphrase gets lost, all files are lost. If you control the hardware, I would recommend keeping file encryption disabled for beginners.

1. Create directory

First create a directory where you place your Compose configuration files.

It is recommended to have the Compose configurations of all your services close together in one directory, for example ~/workspace.docker/ on Linux. Then create ~/workspace.docker/simpledms for the SimpleDMS configuration files.

2. Create docker-compose.yml file

Save the following content as docker-compose.yml in the newly created directory for SimpleDMS.

Please change to values of ROOT_ACCESS_KEY_ID and ROOT_SECRET_ACCESS_KEY with random values for the versitygw service.

Please note that it is important to preserve the spaces as spaces have a meaning in YAML files must be used instead of tabs for indention.

volumes:
  simpledms_data:
  storage_data:

services:
  simpledms:
    image: "ghcr.io/simpledms/simpledms:stable"
    env_file: "simpledms.env"
    depends_on:
      versitygw:
        condition: service_started
      tika:
        condition: service_started
    restart: unless-stopped
    # if you run SimpleDMS locally, you probably want to use other ports
    ports:
      - 7777:80
    volumes:
      - simpledms_data:/srv

  tika:
    image: apache/tika:latest-full
    restart: unless-stopped

  # versity gateway is only necessary if you don't have S3 storage yet
  # and want to store the files in a Docker volume (this example) or on
  # your file system
  versitygw:
    image: versity/versitygw:latest
    restart: unless-stopped
    volumes:
      - storage_data:/data
    environment:
      ROOT_ACCESS_KEY_ID: unsafe-placeholder-access-key-id
      ROOT_SECRET_ACCESS_KEY: unsafe-placeholder-secret-access-key
      VGW_BACKEND: posix
      VGW_BACKEND_ARG: /data

3. Create simpledms.env file

Save the following content as simpledms.env in the newly created directory.

Set the email address for the initial admin account by adjusting SIMPLEDMS_INITIAL_ACCOUNT_EMAIL. The name of the initial tenant can be freely chosen by defining SIMPLEDMS_INITIAL_TENANT_NAME. The tenant name could for example be the name of your company or «Family» or «Homelab».

Further you have to set SIMPLEDMS_S3_ACCESS_KEY_ID and SIMPLEDMS_S3_SECRET_ACCESS_KEY to the values you set in your docker-compose.yml configuration.

At last you have to configure the mailer for the transactional mails (for example your initial password) by setting all variables prefixed with SIMPLEDMS_MAILER_.

SIMPLEDMS_OVERRIDE_DB_CONFIG=false

# initial account and tenant are only created if there exists no account yet.
SIMPLEDMS_INITIAL_ACCOUNT_EMAIL=
SIMPLEDMS_INITIAL_TENANT_NAME=

# WARNING
# must be set on initial setup of app and value must net be changed later;
# not doing so can lead to data loss
# WARNING
SIMPLEDMS_DISABLE_FILE_ENCRYPTION=true

# IMPORTANT
# after the initialization of the app, the following values are stored and read
# from the database; the admin can change them in the app; changing the env vars
# will have no effect after app initialization;
# IMPORTANT

SIMPLEDMS_S3_ENDPOINT=versitygw:7070
SIMPLEDMS_S3_ACCESS_KEY_ID=unsafe-placeholder-access-key-id
SIMPLEDMS_S3_SECRET_ACCESS_KEY=unsafe-placeholder-secret-access-key
SIMPLEDMS_S3_BUCKET_NAME=simpledms
SIMPLEDMS_S3_USE_SSL=false

SIMPLEDMS_TLS_ENABLE_AUTOCERT=false
SIMPLEDMS_TLS_CERT_FILEPATH=
SIMPLEDMS_TLS_PRIVATE_KEY_FILEPATH=
SIMPLEDMS_TLS_AUTOCERT_EMAIL=
SIMPLEDMS_TLS_AUTOCERT_HOSTS=

SIMPLEDMS_MAILER_HOST=
SIMPLEDMS_MAILER_PORT=
SIMPLEDMS_MAILER_USERNAME=
SIMPLEDMS_MAILER_PASSWORD=
SIMPLEDMS_MAILER_FROM="SimpleDMS <noreply@example.com>"
SIMPLEDMS_MAILER_INSECURE_SKIP_VERIFY=false

SIMPLEDMS_OCR_TIKA_URL=http://tika:9998

4. Start services

You can then start the Docker services using your preferred method. On Linux you would do docker compose up -d in the newly created directory.

To inspect the logs you can use docker compose logs.

5. Login

If everything was setup correctly and all services are up and running, you should have received an email with a temporary password to login.

Visit http://localhost:7777 and login with your email address and the temporary password. On the Dashboard, you can set your password.

6. Backups

In this setup, your files and the SimpleDMS metadata is stored in Docker volumes. Your files in the volume storage_data and the metadata in simpledms_data.

It is important to backup these volumes on a regular schedule and monitor the backup creation.

More information

You can find more background information on the SimpleDMS setup in the reference article.

There is also first-steps a tutorial for the first steps in the app.