Maintain and troubleshoot Docker

Docker: experimental, in maintenance mode

The Docker version is functional, but may still be unstable. It is experimental and in maintenance mode: only bug and security fixes, no new features.

Update

1. Back up /config and your model folders as described below.
2. Select the desired IMAGE_TAG in .env. A fixed version stays fixed; the release Compose file also stays on its release version unless overridden.
3. Pull the image and recreate the container:

docker compose pull
docker compose up -d
docker compose ps
docker inspect --format '{{.State.Health.Status}}' "$(docker compose ps -q 3mf-katalog)"

4. Check the app’s version display and open the companion page and the browser desktop.

pull alone does not replace a running container. With the repository file, use up -d --no-build to exclude a local build. For your own builds, set the new matching APP_URL and APP_VERSION, run docker compose build, then docker compose up -d --no-build.

Tag	Meaning in the image workflow
X.Y.Z	A specific stable release version.
X.Y	Highest published stable version in that series.
latest	Highest published stable version; created only with a stable image release.
0.16.0	A specific stable version without v; it never changes. Pre-releases carry a suffix such as 0.16.0-12.
rc	Moving tag set by a publishing RC workflow; does not change latest.

Use separate Compose projects and /config folders for stable and RC. Parallel instances also need different host ports. Automatic RC-to-stable migration is not configured. An older image may not read a newer database schema; keep your pre-update backup.

Full backup

Back up the entire host folder mounted at /config, not just catalog.db. This includes app settings, trash, WebView data, the saved password file, the .katalog-web-secret signing key and the .katalog-web-hidden.json hidden list. By default, the companion searches for the database under /config/.local/share/*/catalog.db. Also back up /models, all other model mounts, your Compose file and .env. Keep backups containing credentials private.

1. Stop the container before copying files:

docker compose stop

2. Copy the complete host config folder, including hidden files, and all model folders using your backup tool. Preserve ownership and permissions. Back up custom mount sources at their actual locations.
3. Start again afterwards:

docker compose up -d

To restore, stop the container, restore the matching backed-up folders with suitable permissions, and retain the same container paths. Start with the image version matching the backup and check the catalog and files.

The app’s ZIP backup contains only catalog.db and settings.json, not models or trash. It does not replace a full backup of the mounts. Reactivate printer connections after importing an app backup; import pauses them.

Logs and restarts

docker compose logs --tail=100 3mf-katalog
docker compose logs -f 3mf-katalog

App output and restart messages appear in container logs. Stop following logs with Ctrl+C. Remove passwords and private details before sharing logs: the first-start log may contain the generated password.

The app service restarts the app after it exits. Rapid failures increase the delay from 2 to 30 seconds; a run lasting at least 60 seconds resets it. Compose allows 30 seconds for SQLite/WAL to close when stopping. docker compose down removes the container and network but preserves mounted host folders.

Troubleshooting

Container will not start or the app keeps restarting

1. Check docker compose ps and logs.
2. Check the tag: it must be a published tag, for example latest (newest stable version) or a fixed version such as 0.16.0.
3. Check credentials for invalid characters, mount permissions and free space. Local builds require APP_URL and APP_VERSION.
4. Open the browser desktop after a restart. A healthy status confirms only the app process and HTTP availability, not every GUI function.

Forgotten password

For generated passwords, read config/.kasmvnc-password using an authorized account. Alternatively, set a valid supplied PASSWORD in .env and recreate the container with docker compose up -d.

For a new random password, stop the container, remove specifically config/.kasmvnc-password, leave PASSWORD empty and start again. The new password appears in the log. A damaged saved file is not replaced automatically; it must contain exactly 48 lowercase hexadecimal characters with an optional trailing newline. A supplied password does not replace that old file.

Permissions, missing models or disabled uploads

Check host sources, PUID/PGID, NAS ACLs and write/traverse permissions. For uploads, the model mount must not be read-only (:ro). KATALOG_UPLOAD_DIR must be inside an allowed root. For missing download buttons, check that the file exists and is inside an allowed root. If the companion is empty, first set up the catalog, then check the database path and read permissions.

Network or FUSE filesystem under /config

Startup warns about detected network/FUSE filesystems and creates /config/.network-filesystem-warning. The app displays a dismissible warning. SQLite needs local storage; otherwise the database may become corrupted. Back up with the container stopped and move /config to a local volume. /models may remain on a NAS share. Filesystem detection is a warning aid, not a guarantee of correct storage locking.

Docker inside Proxmox LXC

The Docker README mentions nesting=1 and keyctl=1 from a tester’s report about Docker in Proxmox LXC. This is not evidence that the project tested that environment. Treat it as a troubleshooting hint, not a verified installation guide.

What “may still be unstable” means

The Docker README lists outstanding tests for 3D previews with many models, restoring trash files and running in LXC. arm64 is unsupported. Software rendering and differences in clipboard, keyboard, file dialogs and WebKit remain limitations. CI scripts check startup, authentication, restarts and signed downloads, among other things; this does not replace complete usability and recovery testing on your server.

Report a problem

Use “Report a bug” in the app, GitHub Issues or Discord. Include the image version, host system, browser, reproduction steps and relevant sanitized logs. Do not share passwords or signed download URLs. More about reporting bugs.