Deployment and configuration

Version scope

This page documents behavior released in stable v0.9.4. Pin an image tag or digest in production instead of using latest. Before upgrading, read the target release notes and repeat your readiness and restore tests.

Recommended Docker deployment

The following command keeps configuration, SQLite, and the local object cache in one named volume:

Terminal

docker volume create depsilo-state

docker run -d --name depsilo \
  -p 23333:23333 \
  -v depsilo-state:/root/.depsilo \
  --restart unless-stopped \
  ghcr.io/depsilo/depsilo:0.9.4

v0.9.4 setup writes absolute database and local-cache paths into its generated configuration, so a new installation only needs to persist /root/.depsilo. The official image runs as UID/GID 10001:10001; new named volumes inherit that ownership. For an older root-running container or v0.9.0 Compose layout, follow the versioned upgrade guide before reopening its state.

State	Path in the container	Purpose
Configuration	/root/.depsilo/config.toml	Generated by setup; may contain sensitive values
SQLite	/root/.depsilo/data/depsilo.db	Authoritative users, policy, audit, and cache metadata
Local object cache	/root/.depsilo/data/cache	Package artifacts; excluded from depsilo backup

When storage.type is s3, only cache objects move to the remote backend. Configuration and SQLite remain local state and still require persistence and backup. An S3 backend does not make v0.9.4 multi-instance or highly available.

Complete first-time setup

docker logs depsilo

Open http://localhost:23333, enter the one-time bootstrap token from the startup log, and create the first administrator. Depsilo has no default admin/admin account. Do not expose startup logs; protect or retire retained bootstrap log data according to your log policy after setup.

Configuration sources and precedence

v0.9.4 resolves the same setting in this order, highest precedence first:

1. CLI flag
2. DEPSILO_* environment variable
3. config.toml
4. Built-in default

For example, server.port maps to DEPSILO_SERVER_PORT and cache.ttl_index maps to DEPSILO_CACHE_TTL_INDEX. Set DEPSILO_CONFIG to select a file. Without it, Depsilo searches ./config.toml, /app/config.toml, and ~/.depsilo/config.toml.

Example values are not defaults

config.example.toml is a complete set of explicit overrides, not a list of defaults. For example, the v0.9.4 built-in cache.ttl_index is 5m, while the example file sets 1h. Review every copied value; copying the example and omitting a setting are not equivalent.

The most deployment-sensitive differences are:

Setting	v0.9.4 built-in default	v0.9.4 example	Production guidance
server.host	0.0.0.0	0.0.0.0	Bind only to a controlled network or protect it with a TLS proxy
server.port	23333	23333	Keep probes and client URLs in sync when changing it
database.dsn	./data/depsilo.db	./data/depsilo.db	Use an absolute path in the container volume
storage.path	./data/cache	./data/cache	Use an absolute path in the container volume
cache.max_size_gb	20	20	Size for artifact volume and disk budget
cache.ttl_index	5m	1h	Choose for your metadata freshness requirement
cache.ttl_blob	72h	72h	Evaluate with capacity and offline tolerance
auth.enabled	true	true	Keep authentication enabled for the admin plane
auth.token_ttl	168h	168h	Shorten to match your session policy

When no configuration file exists, v0.9.4 relocates the effective database and cache defaults under ~/.depsilo/data/ and generates a temporary secure JWT secret for setup. This is special missing-file behavior; it does not make the placeholder in an explicit example configuration safe.

With an explicit configuration, a non-loopback listener refuses to start when auth.jwt_secret = "change-me-in-production". Inject a random value through your secret manager, for example:

export DEPSILO_AUTH_JWT_SECRET="$(openssl rand -hex 32)"

Do not commit the secret or send it through public logs.

Configuration authority for upstreams

On first upgrade or activation, Depsilo seeds ordinary ecosystem upstreams into the database. After that import, Admin and the database are authoritative: restarts do not recreate an upstream that an operator changed or deleted. Adding configuration for a previously inactive supported ecosystem can activate that ecosystem on the next restart.

Docker registries and extra indexes remain configuration-owned and are not managed by ordinary Admin Upstream CRUD. Deployment automation should distinguish these sources rather than treating the file as a continuous source of truth for all runtime state.

Readiness and diagnostics

/ready checks SQLite and object storage and returns a non-2xx response when either is unavailable. It intentionally excludes upstream health because Depsilo may still serve cached packages during an upstream outage.

curl -fsS http://127.0.0.1:23333/ready

docker exec depsilo /app/depsilo doctor
docker exec depsilo /app/depsilo doctor --json

The container image health check also uses /ready. Use it to decide whether an orchestrator should send traffic to the instance; use /health only as a process liveness signal. doctor additionally checks version alignment, storage, upstreams, and cache hit rate. Without DEPSILO_TOKEN it reports fewer protected admin details, but its basic diagnostics still run.

Backup and restore

depsilo backup can create a consistent SQLite snapshot while the service is running. Write the archive to the state volume and copy it to a controlled backup location outside the container:

docker exec depsilo mkdir -p /root/.depsilo/backups
docker exec depsilo /app/depsilo backup \
  --out /root/.depsilo/backups/depsilo-backup.tar.gz
docker cp depsilo:/root/.depsilo/backups/depsilo-backup.tar.gz .

The archive contains only the config.toml file and a consistent SQLite snapshot. It does not contain local or S3 cache objects. Treat it as sensitive because it contains users, policies, audit data, and potentially secret configuration. Encrypt it, restrict access, and copy it outside the deployment failure domain. Protect cache data separately or accept that it will be fetched again.

The service that owns the target database must be stopped before restore. This example uses the same image version and restores an archive from the current directory into the named volume:

Terminal

docker stop depsilo

docker run --rm \
  -v depsilo-state:/root/.depsilo \
  -v "$PWD:/backup:ro" \
  -e DEPSILO_CONFIG=/root/.depsilo/config.toml \
  -e DEPSILO_DATABASE_DSN=/root/.depsilo/data/depsilo.db \
  -e DEPSILO_STORAGE_PATH=/root/.depsilo/data/cache \
  ghcr.io/depsilo/depsilo:0.9.4 \
  restore /backup/depsilo-backup.tar.gz

docker start depsilo
curl -fsS http://127.0.0.1:23333/ready

Practice this in an isolated environment and verify admin login, policies, upstreams, and a client package fetch. A created archive is not a verified restore.

Pre-production checklist

• Pin the 0.9.4 tag, or an image digest when stronger reproducibility is required.
• Expose the service through a TLS reverse proxy or controlled network, and restrict the Admin and setup surfaces.
• Persist configuration, SQLite, and the local cache; apply least privilege to the state volume and backups.
• Put JWT and other secrets in a secret manager, not an image or repository.
• Route traffic with /ready, diagnose the whole path with doctor, and rehearse restores regularly.