Quick Start

PicFast runs in a single Docker container. You just need a PostgreSQL database and the prebuilt image from Docker Hub.

Prerequisites

• Docker
• A PostgreSQL instance (local, remote, or Docker)
• A domain name (for production) or just use localhost for testing

1. Start everything

Three commands: create a Docker network, start PostgreSQL, start PicFast.

docker network create picfast-net

docker run -d --name picfast-db --network picfast-net \
  -e POSTGRES_PASSWORD=devonly \
  -v picfast-pgdata:/var/lib/postgresql/data \
  postgres:16-alpine

docker run -d --name picfast --network picfast-net -p 18080:8080 \
  -e PICFAST_DATABASE_URL='postgres://postgres:devonly@picfast-db:5432/postgres?sslmode=disable' \
  -e PICFAST_JWT_SECRET='change-me-in-production' \
  -e PICFAST_SERVER_BASE_URL='http://localhost:18080' \
  -v picfast-uploads:/app/data/uploads \
  -v picfast-thumbnails:/app/data/thumbnails \
  xbeta/picfast:latest

Available image tags: latest, version tags (vX.Y.Z), and commit-traceable tags (sha-<commit>). See Docker Hub for the full list.

2. Initial setup

Open http://localhost:18080 in your browser. A guided setup wizard helps you create your first admin account.

For headless (non-browser) deployments, set these additional environment variables to auto-create the admin and skip the wizard:

PICFAST_APP_ADMIN_EMAIL=admin@example.com
PICFAST_APP_ADMIN_PASSWORD=your-admin-password

3. Upload your first image

Log into the web UI and drag-drop a file, or use the API:

curl -X POST http://localhost:18080/api/v1/images \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -F "file=@image.png"

For AI agent integration, see MCP Integration. For ShareX one-click setup, see ShareX Integration.

Next steps

• Full configuration reference →
• Set up cloud storage backends →
• API documentation →
• Production deployment with Traefik + Compose →
• Home network & NAS deployment →

Development setup

If you want to build from source or contribute to PicFast:

• Prerequisites: Go 1.26+, Node 20+, pnpm, PostgreSQL 16, Git
• Start services: make docker-up (launches PostgreSQL + Mailpit)
• Run backend: go run ./cmd/picfast
• Run frontend: cd web && pnpm install && pnpm dev

Database migrations run automatically on startup. For bundled serving: cd web && pnpm build && go run ./cmd/picfast.

See the GitHub README for full development instructions.