Quickstart

This guide takes you from zero to a running Weavestream instance.

Step 1 — Download the two files you need

mkdir weavestream && cd weavestream
curl -O https://raw.githubusercontent.com/Weavestream/Weavestream/main/compose.yml
curl -O https://raw.githubusercontent.com/Weavestream/Weavestream/main/.env.example
mv .env.example .env

You can pin to a specific release tag by replacing main with v1.1.1 (or your target version).

Step 2 — Generate random secrets

macOS / Linux / WSL

curl -O https://raw.githubusercontent.com/Weavestream/Weavestream/main/scripts/keygen.sh
chmod +x keygen.sh
./keygen.sh >> .env

Windows (PowerShell)

Invoke-WebRequest `
  -Uri https://raw.githubusercontent.com/Weavestream/Weavestream/main/scripts/keygen.ps1 `
  -OutFile keygen.ps1
.\keygen.ps1 | Out-File -Append -Encoding ascii .env

Open .env in a text editor, delete the REPLACEME placeholder rows at the top, then update DATABASE_URL and REDIS_URL to use the newly generated POSTGRES_PASSWORD and REDIS_PASSWORD values.

Step 3 — Pin a version (recommended)

Edit .env and set a specific release:

WEAVESTREAM_VERSION=1.1.1

Using latest is fine for evaluation but can surface breaking changes without warning. Browse published tags at GitHub Container Registry.

Step 4 — Choose where data lives (optional)

By default, persistent data is stored in ./data/ next to compose.yml. To use a different location (e.g. a NAS share), set DATA_DIR in .env:

DATA_DIR=/volume1/docker/weavestream   # Synology / UGREEN
DATA_DIR=/srv/weavestream               # plain Linux

Docker auto-creates $DATA_DIR/{postgres,redis,files} on first boot.

Step 5 — Start the stack

docker compose up -d

This pulls all images and starts the containers. The api container runs prisma migrate deploy automatically before serving traffic.

Check status:

docker compose ps
docker compose logs -f api

The web UI is available at http://localhost:3000.

Step 6 — Create the first admin

docker compose exec [your-api-container-name] node dist/cli.js create-admin

You will be prompted for an email address and a temporary password.

What's next?

• First Login — complete MFA setup and configure your workspace
• Invite Users — add operators and client users
• Configuration Reference — review all environment variables