Self-hosting

Run Abstractions on your own infrastructure. This page covers prerequisites, local and Docker deploys, environment variables, production hardening, and rebranding.

What you're running

Abstractions is a monorepo with two apps and shared infrastructure:

Browser → Next.js → Go API → Postgres (+ pgvector)
                       └── Redis → Workers

You need the API and the workers process. Without workers, repositories never finish indexing and scheduled newsletters never send.

Prerequisites

1. Go — version in api/go.mod toolchain
2. Node.js 22+ and pnpm 9.15+
3. PostgreSQL 15+ with the vector extension
4. Redis 7+
5. Optional but needed for full production use: AWS SES (email), S3-compatible storage (uploads), Google/GitHub OAuth apps, and AI provider API keys

Run from source

Best for development and for operators who want each process on the host.

Configure the API

cp api/.env.example api/.env

Set at least:

1. SIGNING_KEY and TOKEN_REFRESH_KEY — long random secrets
2. ENCRYPTION_KEY_32_BIT — exactly 32 characters
3. Database and Redis connection settings
4. API_URL and CLIENT_URL — public URLs of the API and frontend

Full list: api/.env.example.

Database

# Create the database, then:
#   CREATE EXTENSION IF NOT EXISTS vector;

cd api
go mod tidy
go run cmd/main.go migrate 0

Migrations apply on every API container start as well (migrate 0 before the server boots).

API and workers

# Terminal 1 — API (default http://localhost:1234)
cd api && go run cmd/main.go

# Terminal 2 — workers (indexing + newsletters)
cd api && go run workers/workers.go

Frontend

cp frontend/.env.example frontend/.env.local
# Set NEXT_PUBLIC_API_URL to your API base URL
cd frontend && pnpm install && pnpm run dev --turbopack

Open http://localhost:3000. For a production frontend build, use pnpm run build and pnpm run start instead of dev.

Docker Compose

The repo ships Compose files that run the API, workers, Redis, and frontend.

# Ensure api/.env exists (see Configure the API above).
# For containers talking to Postgres/Redis on the host, see .env.docker.example.

# Optional: bake the public API URL into the frontend image
export NEXT_PUBLIC_API_URL=http://localhost:1234

docker compose up --build

Default ports:

Postgres is not included in Compose. Point DATABASE_* at your own instance (local, managed, or a separate container you add).

For production, either build your own images or pull from GHCR by setting REPO_OWNER and optional API_TAG / WORKERS_TAG / FRONTEND_TAG. Rebuild the frontend whenever NEXT_PUBLIC_API_URL changes — Next.js inlines that value at build time.

Environment variables

Core

Database and Redis

Email and storage

OAuth

Leave a provider empty to disable it.

Register callback URLs that match your API_URL / CLIENT_URL in each provider's console.

AI keys

Workspaces can always supply their own keys in AI settings. Platform keys are a fallback when you want defaults for your instance.

Frontend

Production checklist

1. Set ENV=production
2. Generate strong values for SIGNING_KEY, TOKEN_REFRESH_KEY, and a random 32-character ENCRYPTION_KEY_32_BIT
3. Point API_URL, CLIENT_URL, and NEXT_PUBLIC_API_URL at your real domains (HTTPS)
4. Use TLS-terminated reverse proxy in front of the API and frontend
5. Run PostgreSQL with vector enabled; prefer managed backups
6. Run Redis with persistence appropriate for your job-retry tolerance
7. Configure SES (or compatible) and verify sending domains
8. Configure OAuth apps with production redirect URIs
9. Run both the API process and the workers process (or both Compose services)
10. Confirm migrations ran (migrate 0 on API start in Docker)

Reverse proxy

An example Nginx config for the hosted product lives at conf/useabstractions.com.conf. Adapt hostnames and certificate paths for your domain. The pattern is:

1. Terminate TLS on Nginx
2. Proxy /api/ to the Go API (strip the /api prefix if you serve the API under a path)
3. Proxy everything else to the Next.js frontend (include WebSocket upgrade headers for HMR only if you need them; production usually does not)

You can also put the API on a separate subdomain (e.g. api.example.com) and set API_URL / NEXT_PUBLIC_API_URL accordingly — no path rewrite required.

Rebranding

This repo ships useabstractions.com branding. If you run your own instance, plan to rebrand:

Trademarks and hosted product branding are not licensed under the AGPL. Do not present a self-hosted instance as the hosted Abstractions product.

Operator notes

1. God mode — set users.god_mode = true in the database for a trusted admin to access /god-mode. There is no public self-elevate endpoint.
2. Test endpoints — when ENV is not production, POST /test/cleanup and POST /test/verify_user are registered for e2e. Leave them off in production by setting ENV=production.
3. E2e mail — addresses ending in @test.arterylabs.com never hit SES. Do not rely on that domain for real delivery.
4. Health — the API container healthcheck hits the HTTP server on port 1234. Keep that port open to your orchestrator or load balancer probes.

License

Abstractions is licensed under the GNU Affero General Public License v3.0. If you modify the program and run it as a network service, you must make the Corresponding Source available to your users under AGPL-3.0 (section 13).

Hosted branding for useabstractions.com is excluded from that license; see Rebranding.

Troubleshooting

API starts but indexing never finishes — the workers process is not running, or it cannot reach Redis. Start workers/workers.go (or the workers Compose service) with the same REDIS_* settings as the API.

Frontend calls the wrong API — NEXT_PUBLIC_API_URL was wrong at build time. Rebuild the frontend image or restart pnpm run dev with the correct .env.local.

Containers cannot reach Postgres/Redis on the host — on Linux set DATABASE_HOST=host.docker.internal and REDIS_HOST=host.docker.internal (see .env.docker.example). Confirm host firewall allows those ports.

Migrations dirty or stuck — from the API directory, force a known version only after inspecting schema_migrations: go run cmd/main.go migrate force <version>. Prefer fixing forward with a new migration when you can.

OAuth redirect fails — callback URLs in Google/GitHub must match your production API_URL / CLIENT_URL exactly, including scheme and trailing path.

Emails never arrive — in development, mail is redirected to DEVELOPMENT_EMAIL. In production, verify SES domain identity, region, and that recipients are not suppressed.

Next steps

1. Getting Started — configure AI, GitHub, and your first repository after the stack is up
2. Configuring AI — providers, models, and prompt enhancements
3. How It Works — indexing, generation, and the job system