Setup & Deployment

Prerequisites

• PostgreSQL 14+ — A running PostgreSQL instance with a dedicated database
• .NET 10 Runtime — Or the .NET 10 SDK for building from source
• RSA Key Pair — For JWT signing (can be generated during setup)
• Environment Variables — See Configuration Reference

Minimum Environment Variables

# Required for any deployment
CUSTOMCONNSTR_OrionRestAPIContextV2="Host=localhost;Database=orion;Username=orion;Password=yourpassword"
ORION_BASE_URL="https://login.yourdomain.com"

# For JWT signing (EnvironmentVariable provider)
ORION_SIGNING_KEY_PRIVATE="<base64-encoded RSA private key>"

Fresh Installation

Configure the minimum required environment variables listed above. No setup flag is needed for a first install: /setup opens automatically while the server has no administrator, and closes itself once the install is complete.

Deploy the compiled Orion application (or run via dotnet run for development).

# Run directly
dotnet OrionRestAPI.dll

# Or via Docker
docker run -e CUSTOMCONNSTR_OrionRestAPIContextV2="..." \
           -e ORION_BASE_URL="..." \
           -p 8080:8080 orion:latest

Open https://login.shanecraven.com/setup in your browser. If ORION_SETUP_KEY is set, append ?key=yourkey to the URL.

Tip: You can restrict access to the setup page by IP address or hostname using ORION_SETUP_ALLOWED_HOSTS. Example: ORION_SETUP_ALLOWED_HOSTS=192.168.1.10,admin.internal.example.com. Hostnames are resolved via DNS on each request. If not set, no IP restriction is applied. Blocked requests receive a 404 as if setup mode is disabled.

The setup wizard will guide you through:

1. Database schema creation — Creates all required tables via EF Core migrations
2. Create organisation — Your first tenant organisation
3. Create admin user — The initial administrator account with email/password
4. Create system account — An initial system account for API access
5. Seed data — Creates the default Orion application and permission requirements

Nothing to remove and no restart required — the setup window closes on its own once the install is complete, and from the moment an administrator exists the remaining steps already require signing in as that administrator.

Upgrading

Replace the application binaries with the new version. Set ORION_AUTO_MIGRATE=true so pending migrations apply at startup; /health returns 503 until the schema matches the code, so a bad rollout fails at the load balancer instead of serving errors.

The setup page will show any pending database migrations that need to be applied.

Click the "Apply" button to run pending EF Core migrations. The page will show progress and any errors.

Once all migrations are applied, disable setup mode and restart.

Schema Migrations

Orion uses Entity Framework Core code-first migrations. When the data model changes between versions, new migrations are included in the build.

• Automatic detection: The /setup endpoint detects pending migrations by comparing the database's migration history with the compiled migration assembly.
• Non-destructive: Migrations are additive — they add columns, tables, or indices. Existing data is preserved.
• Rollback: EF Core migrations can be rolled back, but this requires manual intervention. Always take a database backup before upgrading.
• Diagnostics: Use /setup/diagnostics?key=... to inspect federation configuration state.

Troubleshooting