You can self-host Briefkasten with Docker and docker-compose. The setup is split into two docker-compose files, depending on how much you want to self-host, and how many cloud services you'd like to use.

  1. docker-compose.yml - Contains the frontend and backend of the application.
  2. - Contains a PostgreSQL container as well as a Minio object store container.

Quick Start

Clone the repository to your server.

git clone
  1. Setup the environment variables.

Make a copy of the two .env.example files and fill in at least the below minimum required variables with your favorite text editor. The example files have annotations for the variables.

  1. apps/web/.env.example
  2. apps/backend/.env.example
Web + BackendDATABASE_URLpostgres://username:password@localhost:5432/postgres
WebAUTH_URLYour current URL (i.e. http://localhost:3000)
WebAUTH_SECRETSet to the output of openssl rand -hex 33
WebWORKER_URLURL of the backend application, (i.e. http://localhost:8000/api/v0)
BackendJWT_SECRETThe same secret as you set in your web's AUTH_SECRET

Next, you'll want to setup at least 1 Authentication Provider with Auth.js-related environment variables. We support OAuth providers like Github, Google, Azure, Keycloak and Authentik as well as the Email "Magic Link" provider out of the box. See the apps/web/.env.example for the various environment variables you can set.

For example, the GitHub provider is easy to setup and safe to use. That requires the AUTH_GITHUB_ID and AUTH_GITHUB_SECRET environment variables to be set.

If you want to use the storage containers, you'll want to change some of the default credentials in the file. For more details, check out the Object Storage and Database sections below.

Finally, you can spin up the containers

To start the application containers (database and minio/mc) as well, you can use the following command in the root of the repository.

docker-compose -f docker-compose.yml -f up -d

Now your application should be up and running at the default http://localhost:3000

You can continue by putting localhost:3000 behind a reverse proxy, like nginx or traefik for example.



To setup the PostgreSQL database, checkout out the database service in the file. We can bring up that database separately with the following command.

docker-compose -f up database

If you're running the application with their sveltekasten-web and sveltekasten-backend containers from the docker-compose.yml file, they will automatically apply the initial schema migrations to the database upon startup. Otherwise, checkout the development -> database section for more information on how to run the migrations manually.

After you've setup the database, you'll need to tell the web and backend applications where to find the database. This is done by setting the required DATABASE_URL environment variable in both the apps/web/.env and apps/backend/.env files. This default connection string should work if your applications are running in containers on the same docker network as the database, otherwise you'll need to adjust at least the hostname (database).


Object Storage

The default object storage provider is Cloudflare R2 as it has a generous free plan with 10GB storage and no egress fees. But if you'd like to self-host this service, we've included a minio container setup in the file.

You can start it separately with the following command. Make sure to update the MINIO_ROOT_USER and MINIO_ROOT_PASSWORD environment variables in the file, these will be your bucket access key and secret key, respectively, as well as the login for the minio console (available at the container's port 9001).

docker-compose -f up mc minio

When using the minio container, make sure to update the BUCKET_* related environment variables in the backend apps/backend/.env file. For example, when using the default minio settings, the following environment variables should work.


Don't forget to update the access key and secret key based on what you updated in the definition. Also you may need to update the hostname (minio) in the BUCKET_URL, if your instance of the sveltekasten-backend is not running in a container on the same docker network as the minio container. If your sveltekasten-backend is not running on the same docker network, you'll have to update this to the IP address or full hostname of the minio container.

Last updated on