Skip to main content

Self-Hosted Setup & Configuration

This guide helps you set up a self-hosted Terragnos Core instance for local testing, evaluation, or development environments. You'll configure the platform using Docker Compose, connect to your database, and access the Admin Console for configuration.

Prerequisites​

RequirementDetails
Docker / PodmanDocker Engine 24+ with the docker compose plugin (or Docker Desktop on macOS/Windows).
PostgreSQL client toolspsql is helpful for database administration and debugging.
A Terragnos-issued license bundleYou will receive LICENSE_KEY and LICENSE_PUBLIC_KEY strings from Terragnos.
Optional: RedisOnly required when exercising caching features; otherwise the system falls back to in-memory caches.

Getting the container images​

Terragnos Core is distributed as container images. You can pull them from the Terragnos container registry:

docker pull terragnos/core-api:latest
docker pull terragnos/core-worker:latest
docker pull terragnos/core-db:latest
docker pull terragnos/core-db-setup:latest

Or use the provided docker-compose.yml file which references these images.

Environment configuration​

  1. Copy the sample environment file and customize as needed:

    cp .env.example .env

  2. Provide database, authentication, and licensing secrets. At minimum set:

    DATABASE_URL=postgres://terragnos:terragnos@localhost:5432/terragnos
    AUTH_JWT_SECRET=dev-secret-change-me
    AUTH_DEFAULT_TENANT=default
    AUTH_DISABLED=false
    LICENSE_PUBLIC_KEY=-----BEGIN PUBLIC KEY-----...-----END PUBLIC KEY-----
    LICENSE_KEY=eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...
    LICENSE_STORAGE_SECRET=local-dev-license-secret

    Terragnos supplies the license strings as part of your enterprise contract—never attempt to generate them locally.

  3. Export any additional values required by your deployment (Redis URL, rate limit defaults, etc.).

Database setup​

You can use either the provided PostGIS container or your own PostgreSQL + PostGIS database.

Start the PostGIS container and run migrations:

docker compose up -d db
docker compose --profile setup up db-setup && docker compose --profile setup down

When you are done, stop the database with docker compose down (or leave it running for the next session).

Option B: Use your own PostgreSQL + PostGIS database​

If you prefer to use your own existing PostgreSQL + PostGIS instance:

  1. Ensure your database has the required extensions:

    CREATE EXTENSION IF NOT EXISTS postgis;
    CREATE EXTENSION IF NOT EXISTS pgcrypto;
    CREATE EXTENSION IF NOT EXISTS "uuid-ossp";
    CREATE EXTENSION IF NOT EXISTS pg_trgm;

  2. Update your .env file to point to your database:

    DATABASE_URL=postgres://your_user:your_password@localhost:5432/your_database

  3. Run migrations using the db-setup container:

    docker compose --profile setup up db-setup && docker compose --profile setup down

Note: Terragnos Core works with any PostgreSQL 15+ instance that has PostGIS 3.4+ installed. The provided terragnos-core-db image is optional and only for convenience. You can integrate with existing database infrastructure, managed database services (AWS RDS, Azure Database, Google Cloud SQL), or high-availability setups.

Running the services​

Start the Terragnos Core stack:

docker compose up -d api worker

This starts:

  • API Service – REST/GraphQL API on port 3000
  • Worker Service – Background processing for workflows, automation, and events

View logs:

docker compose logs -f api worker

Access the Admin Console (if included in your deployment) at http://localhost:3001 and configure your JWT token in Settings.

Authentication​

Generate a JWT token for testing using the Admin Console or your own JWT generation tool. The token should include:

  • sub – User identifier
  • tenant – Tenant ID (e.g., "default")
  • roles – Array of role names (e.g., ["owner", "admin"])
  • scope – Permission scope

Configure the token in the Admin Console via Settings → Configure JWT token, or use it directly with API requests:

curl -H "Authorization: Bearer <your-token>" http://localhost:3000/v1/object-types

The JWT secret used to sign tokens must match the AUTH_JWT_SECRET value in your .env file.

Typical workflow​

  1. Ensure the database is running and migrations are applied.
  2. Start the API and worker containers: docker compose up -d api worker.
  3. Access the Admin Console to configure:
    • Object types and schemas
    • Workflows and state machines
    • Automation rules
    • RBAC policies
    • License configuration
  4. Use the REST API or SDKs to interact with the platform programmatically.
  5. Monitor health endpoints: curl http://localhost:3000/v1/health/live

Troubleshooting​

IssueResolution
API cannot connect to PostgresConfirm DATABASE_URL matches your database configuration. For Docker Compose, use db:5432; for external databases, use the actual hostname and port.
License errors (403 License limit exceeded)Verify the provided LICENSE_KEY is loaded in your .env file. Request a refreshed key from Terragnos if it expired.
Containers fail to startCheck container logs: docker compose logs api worker. Ensure all required environment variables are set in .env.
Admin Console not accessibleVerify the console container is running and check firewall/port settings. The console typically runs on port 3001.

Next steps​