Setup
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.
docker-compose.yml- Contains the frontend and backend of the application.docker-compose.storage.yml- Contains a PostgreSQL container as well as a RustFS object store container.
The recommended setup runs both files — a fully self-hosted stack with a local PostgreSQL database and a local RustFS (S3-compatible) object store, no cloud accounts required. This is the green path used in the examples below.
If you'd rather offload the database and/or object storage to a managed cloud service (e.g. a hosted Postgres provider or Cloudflare R2), that's fully supported too — just skip docker-compose.storage.yml and point the relevant environment variables at your provider.
Quick Start
Clone the repository to your server.
- 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.
apps/web/.env.exampleapps/backend/.env.example
| Directory | Variable | Value |
|---|---|---|
| Web + Backend | DATABASE_URL | postgres://username:password@localhost:5432/postgres |
| Web + Backend | BETTER_AUTH_URL | Your current URL (i.e. https://app.company.com) |
| Web + Backend | BETTER_AUTH_SECRET | Set to the output of openssl rand -hex 33 |
| Web | PUBLIC_WORKER_URL | URL of the backend application, (i.e. https://api.company.com) |
Next, you'll want to setup at least 1 authentication provider. Briefkasten v2 uses Better Auth and supports the GitHub and Google OAuth providers, as well as email/password 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 GITHUB_CLIENT_ID and GITHUB_CLIENT_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 docker-compose.storage.yml file. For more details, check out the Object Storage and Database sections below.
Finally, you can spin up the containers
This is the recommended green path: it starts the application and the local database (PostgreSQL) and rustfs (object storage) containers, so the whole stack is self-hosted. Run the following command in the root of the repository.
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.
Details
Database
To setup the PostgreSQL database, checkout out the database service in the docker-compose.storage.yml file. We can bring up that database separately with the following command.
If you're running the application with their briefkasten-web and briefkasten-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 recommended object storage is the self-hosted RustFS (S3-compatible) container included in the docker-compose.storage.yml file — it runs locally with no cloud account required. If you'd prefer a managed provider instead, any S3-compatible service works; Cloudflare R2 is a good option with a generous free plan (10GB storage, no egress fees). To use a cloud provider, skip the rustfs container and point the BUCKET_* variables at your provider.
When self-hosting with RustFS, it comes up as part of the recommended docker-compose.storage.yml setup above. To start it on its own, use the following command. The container reads its credentials from the BUCKET_ACCESS_KEY and BUCKET_SECRET_KEY environment variables, which will also be your bucket access key and secret key, as well as the login for the RustFS console (available at the container's port 9001).
When using the RustFS container, make sure to update the BUCKET_* related environment variables in the backend apps/backend/.env file. The backend creates the bucket automatically on startup. For example, when using the default RustFS 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 docker-compose.storage.yml definition. Also you may need to update the hostname (rustfs) in the BUCKET_URL, if your instance of the briefkasten-backend is not running in a container on the same docker network as the RustFS container. If your briefkasten-backend is not running on the same docker network, you'll have to update this to the IP address or full hostname of the RustFS container.
Last updated on