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.

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=
# if the password is empty, a password is automatically generated and send to
# the initial account email address; you have to change the initial password
# after the first login; the password is valid for one week
SIMPLEDMS_INITIAL_TEMPORARY_PASSWORD=
# The tenant name could be chosen freely, and for example be the name of your 
# company or «Family» or «Homelab».
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

# by default setting the session cookies only works over https or on localhost;
# setting this value to true enables cookies over insecure connections; it is
# not recommended to allow insecure cookies
SIMPLEDMS_ALLOW_INSECURE_COOKIES=false

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

# this value can be set to true to override the config values
# stored in the database after initialization with the env var values; 
# if an env var is set, the app also overriddes the
# database value if the value is an empty string; you have to remove the
# env var if you don't want to reset existing values;
#
# one major advantage of having the config values stored in the database
# is, that they are encrypted, and if you protected your app instance 
# with a passphrase; so you don't need an external secrets manager
SIMPLEDMS_OVERRIDE_DB_CONFIG=false

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
# set to true if your mail provider supports it, otherwise
# the mailer falls back to STARTTLS
SIMPLEDMS_MAILER_USE_IMPLICIT_SSL_TLS=true

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 be able to login now.

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

If you set the SIMPLEDMS_INITIAL_TEMPORARY_PASSWORD environment variable, you can use the defined temporary password.

If you didn't define a password, you should have received an email with a temporary password to login.

If you didn't receive an email because the mailer was not setup correctly, please update the configuration and use the «Password forgotten» function to request a new temporary 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.