Getting started

Quick start

Run your own Inkspace with Docker Compose in about five minutes.

This guide starts Inkspace with the official Compose example: one app container and one PostgreSQL container, with persistent volumes for the database and uploads.

Requirements

  • A Linux, macOS or Windows machine with Docker Engine or Docker Desktop and the Compose plugin.
  • For internet-facing installs, a domain name and a reverse proxy with HTTPS (see Reverse proxy & HTTPS).

1. Get the Compose file

Create a folder for your install and download the example Compose file:

mkdir inkspace && cd inkspace
curl -fsSLo docker-compose.yml \
  https://raw.githubusercontent.com/ak4duy/inkspace/master/docker/docker-compose.example.yml

If you already cloned the repository, you can use docker/docker-compose.example.yml directly instead.

2. Set your secrets

Open docker-compose.yml and replace the placeholder values:

  • POSTGRES_PASSWORD and the password inside DATABASE_URL — use the same strong password in both places.

  • BETTER_AUTH_SECRET — a long random string. Generate one with:

    openssl rand -base64 32

  • BETTER_AUTH_URL — the address people will use in their browser, for example https://stories.example.com. Keep http://localhost:6767 for a local trial.

Keep the secret stable. Changing BETTER_AUTH_SECRET later can sign everyone out and invalidate sessions.

3. Prepare the uploads folder

The example bind-mounts ./uploads into the container. Create it and make it writable by the container user (UID 1000):

mkdir -p uploads
sudo chown -R 1000:1000 uploads

4. Start Inkspace

docker compose up -d

On first start the app waits for PostgreSQL to become healthy, syncs the database schema, and then starts listening on port 6767. Follow the logs with:

docker compose logs -f app

You should see [startup] Database schema is synced. followed by the Next.js server starting.

5. Create the host account

Open http://localhost:6767 (or your BETTER_AUTH_URL) and sign up. The first account becomes the host admin — no invite needed. Everyone after that needs an invite link from an admin.

Continue with First steps to invite your friends.

Troubleshooting

Symptom Fix
DATABASE_URL is required… and the app exits The app needs DATABASE_URL, BETTER_AUTH_URL and BETTER_AUTH_SECRET set.
Database schema sync failed. Refusing to start app. Read the lines above it in the logs. See Upgrading for schema changes that drop data.
Avatar or image uploads fail The uploads folder isn’t writable by UID 1000. Re-run the chown command above.
Sign-in works locally but not on your domain BETTER_AUTH_URL must exactly match the browser-facing origin, including https:// and port.