Develop with Docker Compose

This page is for working on staqly itself. To just run staqly, use the binary or the Docker image: neither needs this repository.

Start from a checkoutCopy Anchor Link

git clone https://github.com/staqly/staqly.git && cd staqly
make dev

You need Docker with Compose v2, make, and for the tests Node (.nvmrc), pnpm and Go. make dev builds the image from your checkout, starts the development stack, waits until it is healthy and opens the dashboard in your browser, already signed in.

Make targetsCopy Anchor Link

Compose filesCopy Anchor Link

Settings go in .env in the repository root (copy .env.example); Compose passes most of them to the container. Apply changes with docker compose up -d. Memory and process limits are STAQLY_MEM_LIMIT (default 640m) and STAQLY_PIDS_LIMIT (default 256).

Development stackCopy Anchor Link

make dev runs compose.yml plus compose.dev.yml, with the image built from your checkout. Compared with compose.yml alone it:

• logs at debug level in text format,
• lets webhooks, schedule endpoints and alerts reach private addresses (WEBHOOK_ALLOW_PRIVATE and NOTIFY_ALLOW_PRIVATE default to true), so they can reach mailpit, n8n or your own receivers on the Docker network,
• sets COOKIE_SECURE=false and PUBLIC_DASHBOARD_URL=http://localhost:8080 (or your DASHBOARD_PORT) by default,
• adds mailpit (staqly-mailpit), which catches every email alert. Open its inbox at http://localhost:8025 (MAILPIT_PORT changes the port). In an email alert use host mailpit, port 1025, TLS none,
• adds MaxIOFS (staqly-maxiofs, an S3-compatible server) and keeps media files there, the way a production server keeps them in AWS S3 or another S3-compatible bucket. The S3 API answers at http://localhost:9000, the web console at http://localhost:9001 (admin / admin; MAXIOFS_PORT and MAXIOFS_CONSOLE_PORT change the ports). The bucket staqly-media and a development-only access key are created on first start; the files live in the staqly-maxiofs volume. STORAGE_DRIVER=disk in .env keeps them in the data volume instead. See Media storage.

Every value above can still be overridden in .env. Stop the stack with make dev-down. compose.yml alone (docker compose up -d --build) builds the same image without the extras.

Images and releasesCopy Anchor Link

The image is built from the Dockerfile in the repository root and published to GitHub Container Registry as ghcr.io/staqly/staqly, for linux/amd64 and linux/arm64. A maintainer publishes a release with make release VERSION=v0.2.0: it tags origin/main (only if CI on that commit passed), and the tag makes CI publish the binaries and the image as v0.2.0 and latest.

To build the image by hand: docker build -t staqly .

Running from source without DockerCopy Anchor Link

For working on staqly itself (to just run it without Docker, use the binary):

pnpm install                                         # once, in the repository root
cd apps/api && go run ./cmd/server                   # Community Edition, data in ./data, listens on 127.0.0.1:3333
pnpm --filter @staqly/platform dev                  # dashboard (Next.js dev server); API_INTERNAL_URL defaults to http://localhost:3333

The repository is a Turborepo with pnpm workspaces. The dashboard lives in apps/platform; the landing page (staqly.ai) is apps/web and the docs site apps/docs. Useful commands from the repository root:

Outside Docker too, every request needs the access token (go run ./cmd/server prints it at start, go run ./cmd/server token prints it again). Add WEBHOOK_ALLOW_LOOPBACK=true when webhook receivers listen on localhost.

n8nCopy Anchor Link

n8n is not part of the stack. Use your own, or the example next to staqly: docker compose -f integrations/n8n/compose.yml up -d — see n8n.

Next stepsCopy Anchor Link