Skip to main content

Installation

This guide covers running OpenPrime locally. For production deployments, see the Deployment Guide.

Most people do not need this page

OpenPrime is available as a hosted product at app.openprime.io — sign in and start there. See the Quickstart for what you need to bring (AWS credentials, a Git repository and a write-capable deploy key).

Running the full stack locally requires the openprime-local-testing orchestration repository, which is private to DevOpsGroup. The public repositories — openprime-app, openprime-app-backend, Injecto, StateCraft, openprime-infra-templates, openprime-keycloak, openprime-postgres — can each be built and run on their own, but the one-command local stack below is not reproducible without access to that private repository.

Prerequisites​

Before installing OpenPrime, ensure you have:

  • Docker Desktop 4.0+ with Docker Compose v2
  • Node.js 18+ (for component development)
  • Git for cloning the repository
  • SOPS and age for secrets management (optional)

Verify Prerequisites​

# Check Docker
docker --version    # Docker version 24.0+
docker compose version  # Docker Compose version v2.20+

# Check Node.js (optional, for development)
node --version      # v18.0.0+
npm --version       # 9.0.0+

Quick Installation​

1. Clone the Repositories​

OpenPrime is not a monorepo — each component lives in its own repository under devopsgroupeu. openprime-local-testing holds the Docker Compose stack that drives the others, and is the private repository noted above:

git clone https://github.com/devopsgroupeu/openprime-local-testing.git  # private
git clone https://github.com/devopsgroupeu/openprime-app.git
git clone https://github.com/devopsgroupeu/openprime-app-backend.git
git clone https://github.com/devopsgroupeu/Injecto.git
git clone https://github.com/devopsgroupeu/StateCraft.git

2. Start Services​

cd openprime-local-testing
npm start

This starts all services:

3. Initialize Secrets (Optional)​

For full functionality, set up encrypted secrets:

npm run env:init       # Create secrets file from template
npm run secrets:edit   # Edit with your credentials

Service Architecture​

Service            Port    Description
─────────────────────────────────────────────────
openprime-app      3000    React frontend
openprime-backend  3001    Express.js API
keycloak           8080    Authentication (OIDC)
injecto            8000    Template processor
statecraft         8001    Terraform state manager
postgresql         5432    Database

Verify Installation​

Check service health:

# All services health check
npm run health

# Individual service checks
curl http://localhost:3000          # Frontend
curl http://localhost:3001/health   # Backend
curl http://localhost:8080/realms/master  # Keycloak
curl http://localhost:8000/health   # Injecto

Default Credentials​

Keycloak Admin Console​

Application Login​

After Keycloak initialization, create a user in the openprime realm or configure an identity provider.

Common Issues​

Port Conflicts​

If ports are already in use:

# Find process using port 3000
lsof -i :3000

# Kill the process
kill -9 <PID>

# Or change ports in docker-compose.yml

Docker Memory​

OpenPrime requires at least 4GB RAM allocated to Docker. Increase in Docker Desktop settings if you experience issues.

Database Connection​

If the backend can't connect to PostgreSQL:

# Check database logs
npm run logs:db

# Reset database
npm run clean
npm start

Next Steps​