Repository navigation
Installation
Home › Getting started › Installation
On this page: Requirements · What runs where · Install with Docker Compose · Reverse proxy and TLS (Nginx) · TURN server for video calls (coturn) · Building from source · WhatsApp (optional)
This page takes you from an empty Linux server to a running Granary that you can sign in to. It is for the person who runs the server. Granary runs as a set of Docker containers started by Docker Compose, with Nginx on the host in front of them. When you finish here, continue with First Steps.
| Resource | Minimum | Recommended |
|---|---|---|
| CPU | 2 cores | 4 cores |
| RAM | 4 GB | 8 GB (the PDF service runs headless Chromium; face matching and speech to text use a lot of CPU) |
| Disk | 20 GB | 50 GB SSD |
| OS | A current Linux with Docker | Ubuntu 22.04 LTS or later, or Debian 12 |
The images are prebuilt for each release (ghcr.io/halogass/granary-*, x86-64), so the server does not compile
anything. Only building from source needs more: about 8 GB of RAM and 10 GB of disk
for the Rust build cache.
- Docker Engine 24 or later with the Compose plugin (v2). Check with
docker --versionanddocker compose version. - Nginx on the host (installed with your package manager), as the reverse proxy.
- Git, to fetch the Compose file, the Nginx config and the example
.env. - Optional: Certbot (Let's Encrypt) or
cloudflared(Cloudflare Tunnel) for a public domain.
All containers publish their ports on 127.0.0.1 only. Nginx on the host listens on ports 80 and 443 and forwards
requests to them.
| Service | What it does | Host port |
|---|---|---|
frontend |
The Next.js web application | 127.0.0.1:3000 |
backend |
granary-api, the HTTP API. On every start it first applies migrations and the seed |
127.0.0.1:8000 |
worker |
Runs background jobs (mail polling, reminders, FX sync, Nary) | none |
beat |
Puts scheduled jobs on the queue (same image as backend) |
none |
db |
PostgreSQL 16 with pgvector (embeddings for AI search) | none |
redis |
Redis 7: cache, job queue, live updates, locks | none |
storage |
SeaweedFS, S3-compatible file storage (uploads, documents, recordings) | 127.0.0.1:9000 |
pdf |
Renders documents to PDF with headless Chromium | none |
face |
Face matching and liveness checks for clock-in | none |
research |
Reads web pages for CRM enrichment and research, behind a filtering proxy | none |
searxng |
Self-hosted web search | none |
stt |
Speech to text for voice notes (faster-whisper on the CPU) | none |
signal |
WebRTC signalling for video calls | 127.0.0.1:3003 |
coturn |
TURN/STUN server so video calls work across networks | host network |
The research and searxng services sit on their own Docker network. They can't reach the database, Redis or
the storage.
git clone https://github.com/halogass/Granary-ERP.git granary
cd granary
git checkout v1.0.2 # the release you run; GRANARY_VERSION in .env matches it
cp .env.example .envOpen .env in an editor and replace every value marked ← CHANGE THIS. Generate each secret separately:
openssl rand -hex 32The values you must set before the first start:
# Keys (each its own random value)
APP_SECRET_KEY=<random> # the master key: set it once, before real data (see below)
JWT_SECRET_KEY=<random, 32+ characters>
NEXTAUTH_SECRET=<random>
SIGNAL_TICKET_KEY=<random>
INTERNAL_AUTH_TOKEN=<random>
# Database
POSTGRES_PASSWORD=<strong password>
DATABASE_URL=postgresql://granary:<same password>@db:5432/granary
# Redis: the URLs must carry the password
REDIS_PASSWORD=<random>
REDIS_URL=redis://:<redis password>@redis:6379/0
CELERY_BROKER_URL=redis://:<redis password>@redis:6379/1
CELERY_RESULT_BACKEND=redis://:<redis password>@redis:6379/2
# S3 storage settings (the names date from the earlier MinIO setup)
MINIO_SECRET_KEY=<strong password>
# Tokens used only between containers
PDF_SERVICE_TOKEN=<random>
FACE_SERVICE_TOKEN=<random>
RESEARCH_SERVICE_TOKEN=<random>
STT_SERVICE_TOKEN=<random>
SEARXNG_SECRET=<random>
# The first account (the Owner), created on the first start
SUPERADMIN_EMAIL=owner@example.com
SUPERADMIN_NAME=Hana Mori
SUPERADMIN_PASSWORD=<strong initial password>
# Your public URLs
APP_URL=https://granary.example.com
SIGNAL_URL=wss://granary.example.com/ws/signal
MINIO_PUBLIC_URL=https://granary.example.com/minio
CORS_ORIGINS=["https://granary.example.com"]
# Keep these as they are (Docker-internal addresses)
INTERNAL_API_URL=http://backend:8000
API_URL=http://backend:8000
# TURN server for video calls
TURN_SECRET=<random>
TURN_EXTERNAL_IP=<the server's public IP>
TURN_URIS=["turn:granary.example.com:3478","turns:granary.example.com:5349"]
# Text inside the e-signature seal
SIGN_SEAL_NAME="Kumo Trading Co."
SIGN_LOCATION=TokyoThings to know about .env:
-
Placeholder secrets stop the start. The API and the worker refuse to start while
JWT_SECRET_KEY,APP_SECRET_KEYorNEXTAUTH_SECRETstill begins with the.env.exampleplaceholder (change-this). The log names the variable, never its value. Other weak secrets (short keys, values starting withtest,password,exampleand similar) don't stop the start: they are logged and the Owner is alerted once per start. -
Compose itself refuses to start without
REDIS_PASSWORD,NEXTAUTH_SECRETandSIGNAL_TICKET_KEY. -
APP_SECRET_KEYencrypts secrets stored in Settings (mail passwords, AI keys). Set it once, before you enter real data: settings encrypted with one key can't be read with another. -
INTERNAL_API_URLandAPI_URLmust stayhttp://backend:8000. The public domain there causes an http-to-https redirect loop that breaks API calls. -
The browser uses its own address for API calls and live updates (Nginx passes them on), so no URL is
baked into the frontend.
SIGNAL_URLis read by the backend at start. -
GRANARY_VERSIONpicks the release of the prebuilt images. Keep it equal to the tag you checked out. - Business settings (taxes, payroll, approval limits, time zone) are not environment variables. You set them in the web interface after the first sign-in.
All variables are described in Configuration.
To test locally without Nginx, use these values instead of the public URLs:
APP_URL=http://localhost:3000
SIGNAL_URL=ws://localhost:3003
CORS_ORIGINS=["http://localhost:3000"]
MINIO_PUBLIC_URL=http://localhost:9000Then open http://localhost:3000 after the first start.
docker compose up -dCompose downloads the prebuilt images for GRANARY_VERSION from GitHub's registry (ghcr.io/halogass/granary-api,
-pdf, -face, -signal, -research, -frontend, -stt) and the stock images (Postgres, Redis, storage,
SearXNG, coturn), then starts everything. To compile them yourself instead, see
Building from source.
docker compose logs -f backend # wait for "listening"
docker compose ps # backend and db show (healthy)On every start the backend container runs three steps in order:
-
granary-migrateapplies pending database migrations, in one transaction under a lock. -
granary-seedadds default data that is missing: permissions and roles, the Owner account (with an employee record), document number sequences, every system setting with its default, the default approval policies, a chart of accounts, the account mapping for automatic ledger posting, and the fiscal periods of the current year. It never overwrites values you have edited. It creates no taxes. -
granary-apistarts serving.
If step 1 or 2 fails, the API does not start. Read docker compose logs backend. Both steps are safe to run
again.
You don't need to create storage buckets. Granary creates each bucket the first time it stores a file there.
The seed creates one superadmin, the Owner, from SUPERADMIN_EMAIL, SUPERADMIN_NAME and
SUPERADMIN_PASSWORD. It is created only while no superadmin exists, so changing these values later has no
effect.
- Open your Granary address (
http://localhost:3000locally, or your domain once Nginx is set up). - Sign in with the email and password from
.env. - Open your profile (My profile) and change the password under Change password.
- Turn on Two-factor sign-in on the same page (see Administration).

Then continue with First Steps.
Nginx runs on the host, not in Docker. The site configuration is infra/nginx/granary.conf. It routes:
| Path | Goes to |
|---|---|
/ |
The frontend (port 3000) |
/api/ |
The backend (port 8000), with a rate limit per address |
/api/v1/auth/login |
The backend, with a stricter rate limit (5 per minute per address, burst 10) |
/api/v1/ai/ |
The backend, unbuffered with a long timeout (Nary streams its answers) |
/api/v1/documents/ |
The backend, 180 s timeout (sending a document renders its PDF) |
/api/auth/ |
The frontend (sign-in sessions) |
/.well-known/oauth-*, /api/v1/mcp/oauth/
|
The backend (browser login for AI clients) |
/ws/signal |
The signalling service (port 3003), WebSocket |
/minio/ |
The storage (port 9000), read-only: links to public files and short signed links to private files |
/health |
The backend health check |
sudo apt-get update && sudo apt-get install -y nginx
sudo cp infra/nginx/granary.conf /etc/nginx/sites-available/granary
sudo ln -s /etc/nginx/sites-available/granary /etc/nginx/sites-enabled/granary
sudo rm -f /etc/nginx/sites-enabled/default
sudo nginx -t && sudo systemctl reload nginx
curl http://localhost/health # {"status":"ok","service":"granary"}
sudo ufw allow 80/tcpFor a server with a public IP and ports 80 and 443 open. Point a DNS A record at the server first.
sudo apt-get install -y nginx certbot python3-certbot-nginx
sudo cp infra/nginx/granary.conf /etc/nginx/sites-available/granary
sudo ln -s /etc/nginx/sites-available/granary /etc/nginx/sites-enabled/granary
sudo rm -f /etc/nginx/sites-enabled/default
sudo sed -i 's/server_name _;/server_name granary.example.com;/' /etc/nginx/sites-available/granary
sudo nginx -t && sudo systemctl reload nginx
sudo certbot --nginx -d granary.example.com \
--email admin@example.com --agree-tos --no-eff-email --redirect
sudo certbot renew --dry-run
sudo ufw allow 80/tcp 443/tcpCertbot adds the HTTPS server block to the live Nginx file. From then on, never copy the repository's
granary.conf over the live file: apply changes to it by hand (see
Backups and Upgrades).
Behind a Cloudflare-proxied DNS record nothing extra is needed: granary.conf trusts the CF-Connecting-IP
header only from Cloudflare's published address ranges, so rate limits and the addresses Granary records are
the real visitor's. When Cloudflare publishes new ranges, add them to the set_real_ip_from list.
No port forwarding or static IP is needed. Set up the HTTP option above first, then install cloudflared,
create a tunnel (cloudflared tunnel create granary), route your hostname to http://localhost:80 in
/etc/cloudflared/config.yml, create the DNS record (cloudflared tunnel route dns granary granary.example.com)
and run it as a service (sudo cloudflared service install). The repository's docs/DEPLOYMENT.md has the full
commands.
Set APP_URL, SIGNAL_URL, MINIO_PUBLIC_URL and CORS_ORIGINS to the https:// domain in .env, then:
docker compose up -d backend worker beat frontendVideo calls are peer to peer (WebRTC). When two people are behind strict firewalls, their media is relayed
through coturn, which runs on the host network with infra/coturn/turnserver.conf.
-
Set in
.env:TURN_SECRET=<random> # shared by coturn and the backend TURN_EXTERNAL_IP=<server public IP> TURN_URIS=["turn:granary.example.com:3478","turns:granary.example.com:5349"]
-
Open the firewall:
sudo ufw allow 3478/tcp 3478/udp 5349/tcp 5349/udp # TURN/STUN sudo ufw allow 49152:65535/udp # relay range
-
Restart:
docker compose up -d coturn backend.
The shipped coturn configuration refuses to relay to private and loopback addresses, so a call can't be used
to reach your internal network. TURN_URIS must be a JSON list.
The prebuilt images cover x86-64 servers. To compile them yourself (another CPU type, or your own changes):
docker compose build # about 8 GB of RAM; the first build takes a while
docker compose up -dThe build tags its result with the same names as the prebuilt images, so Compose runs your build. To go back to
the published images: docker compose pull && docker compose up -d.
On a small server, build on a bigger machine and copy the images over:
# on the build machine, in the repository
docker compose build backend pdf face signal research frontend stt
docker compose config --images | grep granary- | xargs docker save | gzip | ssh <user>@<server> 'gunzip | docker load'Granary does not include a WhatsApp Web bridge. The WhatsApp inbox, sending documents over WhatsApp and Nary's
WhatsApp channel talk to an HTTP service at WHATSAPP_SERVICE_URL with the token WHATSAPP_SERVICE_TOKEN. If
you run such a service, pair it in Settings > Email & WhatsApp > WhatsApp link. Without one these features
show as disconnected.
← Previous: Granary | Next: First Steps →
Getting started
AI in Granary
Using Granary
- Sell
- Approve and sign
- Money
- Buy and make
- People
- Work together
Administration
Developers