Setup Alternatives

Alternative ways to set up Porta beyond the Quick Start Docker Hub path.

Fastest path

If you just want to try Porta, use the Quick Start guide — it's the fastest way to get running with Docker Hub images.

---

Clone & Docker Compose

Use the included Docker Compose file from the repository. Useful if you want to explore the full project or customize the Docker setup.

Prerequisites

• Docker with Docker Compose v2+
• Git

Steps

1. Clone the repository

git clone https://github.com/blendsdk/porta-identity.git
cd porta-identity

2. Configure environment

cp .env.docker .env.docker.local

Edit .env.docker.local and generate your secrets (see Quick Start → Step 2):

Variable	Default	Description
ISSUER_BASE_URL	https://porta.local:3443	Public URL of your Porta instance
COOKIE_KEYS	—	Cookie signing key (must generate)
TWO_FACTOR_ENCRYPTION_KEY	—	2FA encryption key (must generate)
SIGNING_KEY_ENCRYPTION_KEY	—	Signing key encryption (must generate)
PORTA_AUTO_MIGRATE	true	Auto-run database migrations on startup
POSTGRES_PASSWORD	porta_secret	PostgreSQL password

3. Start all services

docker compose -f docker/docker-compose.prod.yml up -d

This starts:

• porta — The Porta OIDC provider (port 3000)
• postgres — PostgreSQL 16 database
• redis — Redis 7 cache

Email Testing

To enable the MailHog email testing UI, start with the dev profile:

docker compose -f docker/docker-compose.prod.yml --profile dev up -d

Then open http://localhost:8025 for the MailHog inbox.

4. Wait for health checks

curl https://porta.local:3443/health

You should see a JSON response with "status": "ok".

5. Bootstrap the admin system

docker exec -it porta-app porta init

This creates the super-admin organization, admin application with RBAC permissions, CLI/GUI clients, and your first admin user. See Quick Start → Step 7 for details.

Non-interactive mode:

docker exec porta-app porta init \
  --email admin@example.com \
  --given-name Admin \
  --family-name User \
  --password 'YourSecurePassword123!'

6. Authenticate the CLI

npm install -g @portaidentity/cli
porta login --server https://porta.local:3443

The standalone CLI opens your browser for OIDC authentication. See porta login for details.

7. Configure your environment

Use the interactive administration shell to create organizations, applications, roles, permissions, users, and clients:

porta admin --server https://porta.local:3443

If you are moving selected data from another Porta installation, use Environment Portability to export a JSON manifest from the source and preview it before import.

Stopping

docker compose -f docker/docker-compose.prod.yml down

# Remove data volumes too (fresh start):
docker compose -f docker/docker-compose.prod.yml down -v

---

Source Development Setup

Full development environment for contributing to Porta or running from source.

Prerequisites

• Node.js ≥ 22.0.0
• Yarn Classic 1.22 (NOT npm, NOT Berry)
• Docker + Docker Compose (for infrastructure services)

Steps

1. Clone and install

git clone https://github.com/blendsdk/porta-identity.git
cd porta-identity
yarn install

2. Configure environment

cp .env.example .env

Edit .env and generate your secrets (see Quick Start → Step 2).

The defaults in .env.example work for local development with the Docker-based infrastructure (MailHog for email on port 1025).

3. Start infrastructure

yarn docker:up

This starts PostgreSQL 16, Redis 7, and MailHog using Docker Compose.

4. Build and initialize

# Compile TypeScript
yarn build

# Run database migrations
yarn porta migrate up

# Bootstrap admin system (interactive)
yarn porta init

5. Start the development server

yarn dev

The server starts with hot-reload via tsx watch on https://porta.local:3443.

6. Run tests

# Full verification (lint + build + test)
yarn verify

# Or individually:
yarn lint              # ESLint
yarn test:unit         # Unit tests only
yarn test:integration  # Integration tests (requires docker:up)

Stopping

yarn docker:down

---

Next Steps

• 📖 Quick Start — The primary setup guide
• 🔁 Environment Portability — Selective manifest export and import
• ⚙️ Environment Variables — Complete configuration reference
• 🚢 Deployment Guide — Production deployment guidance