GoTipe Cloud
The self-hosted GoTipe backend — documents, real-time collaboration, exports and an AI proxy — and how to run and configure it.
GoTipe Cloud is a backend you run yourself. It stores documents, serves real-time collaboration for the WASM engine, converts documents in background jobs, and proxies AI requests so provider keys stay on your server. It is a Go service in apps/cloud of the GoTipe repository. GoTipe does not operate a hosted instance.
Use it when you want those pieces without writing your own server. If you already have one, you can use the editor packages without Cloud: the editor never requires it.
Components
| Part | What it does |
|---|---|
REST API, port 8080 |
Accounts, API keys, documents, comments, versions, sharing, organizations, export jobs, AI, Stripe billing. See REST API. |
Sync server, port 8081 |
The /sync WebSocket for collaborative editing. See Real-time sync. |
Metrics, port 9090 |
Prometheus /metrics. |
| Workers | Export jobs, hourly cleanup, Stripe event processing, daily usage totals. |
gotipe-convert |
The native converter for exports and for reading collaborative documents. |
| PostgreSQL | Accounts, document metadata, collaboration updates, jobs, usage, audit log. |
| Valkey | Rate limits, idempotency keys, token revocation. |
| S3-compatible storage | Document bodies, version snapshots, export files (Cloudflare R2, MinIO or another S3 API). |
The API, the sync server, metrics and the workers run in one process. The Docker image also contains gotipe-convert, which the API starts for each conversion. PostgreSQL, Valkey and object storage are separate services.
Run with Docker Compose
infra/docker-compose.yml runs the API behind Caddy (automatic TLS) with PostgreSQL 17, PgBouncer and Valkey 8; Prometheus and Grafana are in the monitoring profile. Object storage is external. Start in the repository root.
1. Build the image under the name the compose file expects:
docker build -f apps/cloud/Dockerfile -t ghcr.io/gotipe/cloud-api:local .2. Create a P-256 key pair for signing access tokens:
openssl ecparam -name prime256v1 -genkey -noout -out jwt-private.pem
openssl ec -in jwt-private.pem -pubout -out jwt-public.pem3. Write infra/.env. Compose reads it for its own variables and passes it to the API. Start from the example, which uses the API's own names and formats (a test loads it through the API's configuration loader), and replace every CHANGE_ME and example.com value:
cp infra/.env.example infra/.envAt least set API_HOST, SYNC_HOST, HTTP_ALLOWED_ORIGINS, SYNC_ALLOWED_ORIGINS, POSTGRES_PASSWORD, R2_ACCOUNT_ID, R2_ACCESS_KEY_ID, R2_SECRET_ACCESS_KEY, R2_BUCKET and GRAFANA_ADMIN_PASSWORD. Then append the keys as quoted multi-line values:
printf 'JWT_PRIVATE_KEY="%s"\nJWT_PUBLIC_KEY="%s"\n' "$(cat jwt-private.pem)" "$(cat jwt-public.pem)" >> infra/.envFor another S3 service, set S3_ENDPOINT (and S3_USE_PATH_STYLE=true if it needs path-style URLs) instead of R2_ACCOUNT_ID; the access key variables keep their R2_ names. The bucket must exist.
4. Set your host names. Nothing in infra/ names a domain. API_HOST (the REST API) and SYNC_HOST (the /sync WebSocket) in infra/.env are the host names Caddy serves and gets TLS certificates for; point their DNS records at the server before the first start. Compose passes both to Caddy and stops with a message when one is missing. It requires HTTP_ALLOWED_ORIGINS and SYNC_ALLOWED_ORIGINS as well; set them to your app's origins (an empty value allows no browser origin). In production the API itself refuses to start without HTTP_ALLOWED_ORIGINS: it has no built-in production origins. After changing a host name on a running stack, recreate Caddy with docker compose up -d caddy.
The API image is ghcr.io/gotipe/cloud-api:$IMAGE_TAG. To pull it from another registry, set CLOUD_IMAGE (the name without the tag) in infra/.env.
Caddy has the fixed address 172.30.240.2 on the compose backend network (172.30.240.0/24), and the API sets TRUSTED_PROXIES=172.30.240.2/32: it takes the client address from X-Forwarded-For only when Caddy sent the request, so the login limit counts each client separately. Caddy sends one address there, the client as it resolved it ({client_ip}). If that subnet is taken on your host, change the subnet, Caddy's ipv4_address and TRUSTED_PROXIES together.
If a CDN or load balancer sits in front of Caddy, configure it in Caddy only: add its ranges to trusted_proxies and enable trusted_proxies_strict in Caddy's global options, as the comment in infra/Caddyfile shows. Caddy then forwards the client that proxy reports. Leave TRUSTED_PROXIES at Caddy's address.
5. Apply the schema. Migrations connect to PostgreSQL directly, not through PgBouncer:
cd infra
export IMAGE_TAG=local
docker compose up -d postgres pgbouncer valkey
docker compose run --rm --entrypoint /bin/sh api -c \
'export DATABASE_URL="postgres://gotipe:${POSTGRES_PASSWORD}@postgres:5432/gotipe?sslmode=disable"; exec /usr/local/bin/gotipe-cloud migrate up'migrate up is safe to run on every deploy: applied migrations are skipped, and a changed migration file stops the run.
6. Start everything and check readiness:
docker compose up -d
docker compose exec api wget -qO- http://localhost:8080/readyz7. Create the first account — see Authentication.
At startup the API logs its trusted proxies (trusted_proxies=172.30.240.2/32). When a request from any other address carries X-Forwarded-For or X-Real-IP, it logs a warning, at most once a minute: behind a proxy this means TRUSTED_PROXIES does not match the proxy, and every client shares one login limit.
Upgrading a host set up before the fixed subnet
Docker does not change the subnet of an existing network. On a host whose stack was created before the backend network had a fixed subnet, Caddy would keep a dynamic address, TRUSTED_PROXIES would match nothing, and a later up of Caddy would fail. infra/scripts/deploy.sh checks the network and stops with these steps. Recreate the containers and networks once; volumes and data are kept:
docker compose -f infra/docker-compose.yml --profile monitoring down
infra/scripts/deploy.sh <tag>
IMAGE_TAG=<tag> docker compose -f infra/docker-compose.yml up -dAdd --profile monitoring to the last command if you run Prometheus and Grafana.
Local development
infra/docker-compose.dev.yml starts PostgreSQL (5432, user and password gotipe), Valkey (6379) and MinIO (9000, user and password minioadmin, bucket gotipe-data). Run the API with Go 1.26, a locally built converter and the key pair from step 2 above:
docker compose -f infra/docker-compose.dev.yml up -d
pnpm build:converter
export DATABASE_URL="postgres://gotipe:gotipe@localhost:5432/gotipe?sslmode=disable"
export S3_ENDPOINT=http://localhost:9000 S3_USE_PATH_STYLE=true
export R2_ACCESS_KEY_ID=minioadmin R2_SECRET_ACCESS_KEY=minioadmin
export JWT_PRIVATE_KEY="$(cat jwt-private.pem)" JWT_PUBLIC_KEY="$(cat jwt-public.pem)"
export GOTIPE_EXPORT_COMMAND="$PWD/target/release/gotipe-convert"
go -C apps/cloud run ./cmd/api migrate up
go -C apps/cloud run ./cmd/apiIn development, the API allows the origins http://localhost:3000, http://localhost:5173 and their 127.0.0.1 forms unless HTTP_ALLOWED_ORIGINS is set.
Configuration
The API reads environment variables only; infra/.env.example lists all of them. Durations are Go durations such as 30s or 1h (a bare number such as 3600 is rejected); rate limits are <count>/<s|sec|min|h|hour>. An invalid value stops the API at startup.
| Variable | Default | Description |
|---|---|---|
DATABASE_URL |
required | PostgreSQL connection URL. |
DATABASE_MAX_CONNS, DATABASE_IDLE_CONNS |
50, 10 |
Pool size and connections kept open. |
VALKEY_URL, VALKEY_PASSWORD |
redis:, — |
Valkey (or Redis) connection. |
R2_ACCOUNT_ID |
— | Cloudflare account; sets the R2 endpoint. |
S3_ENDPOINT, S3_USE_PATH_STYLE |
—, false |
Any S3-compatible endpoint; overrides R2_ACCOUNT_ID. Export download URLs point at this endpoint, so clients must reach it. |
R2_ACCESS_KEY_ID, R2_SECRET_ACCESS_KEY |
— | Object storage credentials, for R2 or S3. |
R2_BUCKET |
gotipe-data |
Bucket for documents, versions and exports. |
JWT_PRIVATE_KEY, JWT_PUBLIC_KEY |
required | PEM text of a matching ECDSA P-256 pair (SEC 1 private key, PKIX public key). |
JWT_ISSUER, JWT_AUDIENCE |
gotipe, gotipe-cloud |
Checked on every token. |
JWT_EXPIRY |
1h |
Access token lifetime. |
ENVIRONMENT |
development |
development or production. Sets default CORS origins and the API key prefix. |
HTTP_ALLOWED_ORIGINS |
development: local dev servers | Exact browser origins for the REST API, comma-separated. Required in production: without it the API stops at startup; an empty value allows no browser origin. The compose stack requires it. |
SYNC_ALLOWED_ORIGINS |
— | Exact browser origins for /sync, comma-separated. Wildcards are rejected. |
TRUSTED_PROXIES |
— | Reverse proxies whose X-Forwarded-For (or X-Real-IP) names the client: IP addresses or CIDR ranges, comma-separated. The API reads the header right to left and takes the first address outside this list, so list every proxy that appends to it, or have the last proxy send only the client (as the compose stack's Caddy does). Empty trusts no proxy; a range that covers every address is rejected. |
LISTEN_ADDR, SYNC_LISTEN_ADDR, METRICS_LISTEN_ADDR |
:8080, :8081, :9090 |
Listen addresses. |
PROMETHEUS_ENABLED |
true |
Serve /metrics. |
RATE_LIMIT_API, RATE_LIMIT_AI, RATE_LIMIT_WS |
100/min, 60/min, 1000/min |
Requests per user, AI requests per user, messages per WebSocket. |
SYNC_TRANSACTION_LIMIT |
16777216 |
Bytes of one collaboration transaction a client may send in parts, 1 MiB to 30 MiB. One API process buffers at most eight such transactions at once. |
EXPORT_WORKERS |
4 |
Parallel export jobs, 1–16. |
EXPORT_POLL_INTERVAL |
1s |
How often idle workers look for jobs. |
EXPORT_MAX_DOCUMENT_SIZE |
10485760 |
Largest document body in bytes, at most 64 MiB. Request bodies may be 1 MiB larger. |
EXPORT_R2_PREFIX |
exports/ |
Key prefix for export files. |
GOTIPE_EXPORT_COMMAND |
gotipe-convert |
Path of the converter binary. |
OPENAI_API_KEY, ANTHROPIC_API_KEY, GOOGLE_AI_API_KEY |
— | Provider keys for /v1/ai/complete. |
AI_DEFAULT_PROVIDER, AI_DEFAULT_MODEL |
openai, gpt-4o-mini |
Used when a request names none. |
AI_MAX_TOKENS |
4096 |
Default and largest max_tokens. |
STRIPE_SECRET_KEY, STRIPE_WEBHOOK_SECRET |
— | Stripe billing; without the webhook secret the webhook answers 503. Send the endpoint customer., checkout., checkout., invoice.paid and invoice.; any API version works. |
STRIPE_PRICE_STARTER_ID, STRIPE_PRICE_PRO_ID, STRIPE_PRICE_BUSINESS_ID |
— | Stripe prices of the paid plans. |
LOG_LEVEL, LOG_FORMAT |
info, json |
debug, info, warn or error; json or text. |
infra/.env also holds variables that only Compose reads: API_HOST and SYNC_HOST (for Caddy), CLOUD_IMAGE, POSTGRES_PASSWORD and GRAFANA_ADMIN_PASSWORD. IMAGE_TAG comes from the shell; infra/scripts/deploy.sh <tag> sets it and pulls that tag of CLOUD_IMAGE. For the image built on the server in step 1, run infra/scripts/deploy.sh --no-pull local.
Older drafts named ENV, JWT_PRIVATE_KEY_PATH, STRIPE_PRICE_STARTER, S3_BUCKET, OAUTH_*, AI_CACHE_TTL, VALKEY_MAX_CONNS and R2_CDN_URL; the API does not read them.
Health and metrics
GET /healthzanswers200 {"status":"ok"}while the process runs.GET /readyzchecks PostgreSQL, Valkey and the bucket at the same time, within 3 seconds. It answers200with{"status":"ok","checks":{"postgres":"ok","valkey":"ok","r2":"ok"}}, or503with"status":"degraded"and"unavailable"for each failing dependency. The response never contains the error; the API logs it asreadiness check failedwith the dependency's name. The image's health check uses this endpoint.GET /metricson port9090serves Go runtime and process metrics and:
| Metric | Labels | Meaning |
|---|---|---|
gotipe_http_requests_total |
method, path, status |
REST requests. path is the route pattern, such as /; requests that match no route have unmatched. |
gotipe_http_request_duration_seconds |
method, path |
REST request duration histogram. |
gotipe_ai_requests_total |
provider, model, status |
Calls to an AI provider, success or error. A failed call's model is unknown and an unknown provider is other, so request fields cannot create new series. |
gotipe_documents_total |
— | Stored documents, counted in PostgreSQL at most once a minute. Missing from a scrape when the count fails. |
gotipe_valkey_used_memory_bytes, gotipe_valkey_maxmemory_bytes |
— | Valkey's used_memory and maxmemory (0 means no limit), read with INFO memory at each scrape. Missing when Valkey does not answer. |
gotipe_websocket_connections, gotipe_websocket_rooms |
— | Open /sync connections and rooms. |
gotipe_export_jobs_total |
format, status |
Finished export jobs, completed or failed. |
infra/prometheus.yml scrapes api:9090. The compose stack runs no exporters; the alert rules and the Grafana dashboards use only the metrics above. ValkeyMemoryHigh fires when Valkey uses more than 80% of maxmemory, and the overview dashboard shows the same ratio. For PostgreSQL, PgBouncer or disk alerts, add the matching exporter and scrape job.
On SIGTERM the API stops accepting requests, finishes open ones for up to 30 seconds, closes the collaboration rooms and stops the workers. Every acknowledged collaboration update is already in PostgreSQL, so nothing is saved at shutdown.
Valkey
Valkey holds token revocations, idempotency records and rate-limit windows, each with its own expiry. None of it is a cache: evicting a revocation would make a revoked token work again, and evicting an idempotency record would let a retry repeat a mutation. infra/valkey/valkey.conf therefore sets maxmemory 1gb with maxmemory-policy noeviction; the policy covers the whole instance, not one database. Do not point the API at a Valkey or Redis that evicts keys (allkeys-* or volatile-* policies).
When the instance is full, Valkey refuses writes and most API requests answer 503 until keys expire: rate-limit windows after one window, idempotency records after 24 hours. Size maxmemory for a day of idempotency records — a stored reply is at most 256 KiB. The API exports Valkey's used_memory and maxmemory on /metrics, and the ValkeyMemoryHigh alert fires at 80%.
Backups
The compose stack does not archive WAL. infra/postgres/postgresql.conf sets archive_mode = off: the stock postgres:17-alpine image has no pgBackRest, and a failing archive_command makes PostgreSQL keep every WAL segment until the disk is full.
Without archiving, take logical backups and copy them off the server:
docker compose -f infra/docker-compose.yml exec -T postgres \
pg_dump -U gotipe -Fc gotipe > "gotipe-$(date +%F).dump"Document bodies, versions and export files live in the bucket, not in PostgreSQL; back up the bucket separately.
For point-in-time recovery with pgBackRest instead:
- Run PostgreSQL from an image that adds pgBackRest to PostgreSQL 17, and mount
infra/pgbackrest/pgbackrest.confat/etc/pgbackrest/pgbackrest.conf. - Give that container
PGBACKREST_REPO1_S3_ENDPOINT,PGBACKREST_REPO1_S3_KEY,PGBACKREST_REPO1_S3_KEY_SECRETandPGBACKREST_REPO1_CIPHER_PASS. pgBackRest does not expand variables inside its configuration file. Thegotipe-backupsbucket must exist. - Create the stanza as the
postgresuser:docker compose exec -u postgres postgres pgbackrest --stanza=gotipe stanza-create. - In
infra/postgres/postgresql.conf, setarchive_mode = onandarchive_command = 'pgbackrest --stanza=gotipe archive-push %p', then restart PostgreSQL. - Run
pgbackrest --stanza=gotipe checkthe same way. Only when it succeeds, take a full backup and scheduleinfra/scripts/backup-cron.
With archiving on, watch disk space and failed_count in pg_stat_archiver: while archive_command fails, WAL accumulates. infra/scripts/restore.sh assumes this setup. The release checks did not run it; rehearse a restore before you rely on it.
Limitations
The compose stack is a starting point, not a tested production setup: the release checks ran the image against PostgreSQL, Valkey and MinIO directly. Review it before you rely on it.
- Without the pgBackRest setup above there is no point-in-time recovery.
- The monitoring profile publishes Prometheus (
9090) and Grafana (3000) on every host interface, and Grafana's admin password falls back toadminwhenGRAFANA_ADMIN_PASSWORDis unset. Keep both off the public network. - Collaboration rooms live in the API process. Run one API process per deployment, or route every connection to a document to the same process.