Configuration

Spoolman is configured with environment variables. There is no configuration file with its own format — the .env file used by the standalone install is just a list of environment variables that gets loaded before Spoolman starts.

Everything on this page takes effect at startup, so Spoolman needs a restart after any change.

Note

A few things are not environment variables: currency, price rounding, extra fields, locations and the URL printed on QR labels are stored in the database and are changed in the web UI under Settings. Those apply immediately, no restart needed.

The file .env.example in the repository always lists every available option with its default, and is the first place new options show up.

Where to put the settings

Docker

Add them to the environment: section of your docker-compose.yml:

services:
  spoolman:
    image: ghcr.io/donkie/spoolman:latest
    restart: unless-stopped
    volumes:
      - type: bind
        source: ./data
        target: /home/app/.local/share/spoolman
    ports:
      - "7912:8000"
    environment:
      - TZ=Europe/Stockholm
      - PUID=1000
      - PGID=1000
      - SPOOLMAN_LOGGING_LEVEL=DEBUG

Then apply the change:

docker compose up -d

Important

Use docker compose up -d, not docker compose restart. A plain restart reuses the existing container and your new settings are ignored.

If you would rather keep the settings in a file, put them in a file and point Compose at it with env_file::

services:
  spoolman:
    env_file: .env

Important

A .env file sitting next to docker-compose.yml is not automatically passed to the container. Compose only uses it to fill in ${PLACEHOLDER} values inside the yaml itself. You have to name it with env_file: as above for Spoolman to see it.

For docker run, pass each variable with -e, or the whole file with --env-file .env.

Standalone

The installer creates a .env file in your Spoolman folder (typically ~/Spoolman/.env) by copying .env.example. That is the file to edit:

nano ~/Spoolman/.env
sudo systemctl restart Spoolman

The format is one KEY=value per line, with # starting a comment. Uncomment a line to enable it:

# Logging level: DEBUG, INFO, WARNING, ERROR, CRITICAL
SPOOLMAN_LOGGING_LEVEL=DEBUG

Important

Leave SPOOLMAN_HOST and SPOOLMAN_PORT set to something. Unlike the other options they have no default in a standalone install — they are passed straight to the web server, which refuses to start if they are empty.

The file is read by the shell, so a value containing spaces or # needs quoting: SPOOLMAN_DB_PASSWORD="my pass#word".

How the standalone service works

Knowing the chain helps when something does not apply:

1. systemd runs the unit /etc/systemd/system/Spoolman.service, which
2. runs scripts/start.sh in your Spoolman folder, which
3. activates the Python environment in .venv, loads every variable from .env, and
4. starts the server on SPOOLMAN_HOST:SPOOLMAN_PORT.

Useful commands:

sudo systemctl restart Spoolman     # apply a change to .env
sudo systemctl status Spoolman      # is it running?
sudo journalctl -u Spoolman -f      # follow the logs
sudo systemctl disable Spoolman     # stop starting it at boot

If you did not install the systemd service, start Spoolman manually with bash scripts/start.sh from the Spoolman folder — it reads the same .env.

Note

The update commands on the Installation page copy your .env over to the new installation folder, so your settings survive an update. New options do get added to .env.example over time, so it is worth comparing your file against it after updating: diff ~/Spoolman/.env ~/Spoolman/.env.example.

The settings

Database

By default Spoolman uses a SQLite database file, which needs no configuration and is what most people should use. Set these only if you want to connect to an existing PostgreSQL, MySQL/MariaDB or CockroachDB server.

Variable	Default	Description
SPOOLMAN_DB_TYPE	SQLite	sqlite, postgres, mysql or cockroachdb.
SPOOLMAN_DB_HOST	—	Database server hostname.
SPOOLMAN_DB_PORT	—	Database server port.
SPOOLMAN_DB_NAME	—	Database name. Not valid with SQLite — see below.
SPOOLMAN_DB_USERNAME	—	Login username.
SPOOLMAN_DB_PASSWORD	—	Login password.
SPOOLMAN_DB_PASSWORD_FILE	—	Path to a file containing the password, for use with Docker secrets. Takes precedence over SPOOLMAN_DB_PASSWORD.
SPOOLMAN_DB_QUERY	—	Extra connection parameters, e.g. unix_socket=/path/to/mysql.sock to connect over a MySQL socket.

Important

With SQLite, do not set SPOOLMAN_DB_NAME — Spoolman refuses to start if you do. The database file is always spoolman.db inside the data directory; move it with SPOOLMAN_DIR_DATA instead.

File locations

Variable	Default	Description
SPOOLMAN_DIR_DATA	~/.local/share/spoolman (/home/app/.local/share/spoolman in Docker)	Where the SQLite database lives.
SPOOLMAN_DIR_BACKUPS	<data dir>/backups	Where automatic backups are written.
SPOOLMAN_DIR_LOGS	<data dir>	Where spoolman.log is written.
SPOOLMAN_AUTOMATIC_BACKUP	TRUE	Nightly backup of the SQLite database, keeping the last 5. Has no effect on other database types.

Important

The default backup directory is inside the data directory, so a lost volume takes the backups with it. Point SPOOLMAN_DIR_BACKUPS somewhere else, or copy the backups off the machine. See Backup and Restore.

In Docker these are paths inside the container, so changing them without also changing your volume mount will put the data somewhere that is not persisted. Usually you want to leave them alone and change the source: of the volume instead.

Network

Variable	Default	Description
SPOOLMAN_HOST	0.0.0.0	Address to listen on. 0.0.0.0 means every network interface.
SPOOLMAN_PORT	8000 in Docker, 7912 in the standalone .env	Port to listen on. In Docker, prefer remapping with ports: instead of changing this.
SPOOLMAN_BASE_PATH	—	Serve Spoolman under a sub-path, e.g. /spoolman to reach it at myhost.com/spoolman. Needed when a reverse proxy hosts it below the root.
SPOOLMAN_CORS_ORIGIN	—	Extra browser origins allowed to talk to Spoolman. See Security.
SPOOLMAN_ALLOWED_HOSTS	off	Hostnames this instance answers to, as protection against DNS rebinding. See Security.

External filament catalog

Spoolman fetches a community-maintained catalog of known filaments so you do not have to type in every spool by hand.

Variable	Default	Description
EXTERNAL_DB_URL	https://donkie.github.io/SpoolmanDB/	URL of the catalog. Set to an empty value to disable the feature entirely, or point it at your own catalog.
EXTERNAL_DB_NAME	SpoolmanDB	Display name shown in the UI. Change it if you use your own catalog.
EXTERNAL_DB_SYNC_INTERVAL	3600	How often to re-fetch the catalog, in seconds. Set to 0 to only fetch it at startup.

Note

These are the only settings without a SPOOLMAN_ prefix. That is historical — renaming them would break existing setups.

Diagnostics and other

Variable	Default	Description
SPOOLMAN_LOGGING_LEVEL	INFO	DEBUG, INFO, WARNING, ERROR or CRITICAL. DEBUG also logs every SQL statement, which is what to attach to a bug report.
SPOOLMAN_METRICS_ENABLED	FALSE	Populate the Prometheus metrics at /metrics. Read the note on what this exposes first.
SPOOLMAN_LEGACY_CLIENT	FALSE	Serve the previous web client instead of the current one. Both ship in the same image and use the same API, so this is a safe fallback if the current client misbehaves on your setup — your data is untouched either way. Please report the problem if you need this.
SPOOLMAN_DEBUG_MODE	FALSE	For development only. Turns off the browser origin checks entirely and returns internal error details to callers. Do not enable it on a machine you care about.
TZ	UTC	Timezone, in Docker. Affects timestamps in logs and in the UI.

Docker user

Only relevant in Docker. These control which user inside the container owns the files it writes, and are the usual fix for permission errors on the mounted data folder.

Variable	Default	Description
PUID	1000	User ID Spoolman runs as. Must match the owner of your mounted data directory. Cannot be 0.
PGID	1000	Group ID Spoolman runs as.

Run id -u and id -g on the host to find yours. If Spoolman cannot write to its data directory it says so at startup and tells you which chown to run.

Where your data ends up

With default settings, the data directory contains:

spoolman.db          the database
spoolman.log         the log file, rotated at midnight, 5 kept
backups/             nightly database backups, 5 kept
cache/               the downloaded external filament catalog

In Docker that directory is /home/app/.local/share/spoolman, which is the path you should have mounted a host folder onto. If you cannot find spoolman.db on your host, the mount is wrong and your data will be lost on the next update — see Backup and Restore for where the file should be. Spoolman also warns loudly in the log at startup when it detects that the data directory is not mounted.

Checking your configuration

Spoolman logs what it resolved at startup, so the logs are the fastest way to confirm a setting arrived:

docker compose logs          # Docker
sudo journalctl -u Spoolman  # standalone

Look for the database it connected to, the data directory it is using, and warnings about the security settings. A misspelled value stops startup with a message naming the variable, for example Failed to parse SPOOLMAN_LOGGING_LEVEL variable: .... A misspelled variable name is silently ignored, so if a setting seems to do nothing, check its spelling against .env.example first.