Quick start

This guide runs the full OpsNexus stack on one machine with Docker Compose. It takes about ten minutes, most of it spent building the images.

#Requirements

• Docker 24 or later with the Compose plugin (docker compose). On Windows and macOS, Docker Desktop works.
• Git, to clone the repository.
• A free TCP port for the web app. The default is 8080.
• A free port on 127.0.0.1 for the Vault UI. The default is 18200.

You do not need Python, Node.js or PostgreSQL on the host. Everything runs in containers.

#1. Clone the repository

git clone https://github.com/Jeyanth-Ops/OpsNexus.git
cd OpsNexus

#2. Create the .env file

Copy the example file:

cp .env.example .env

On Windows PowerShell:

Copy-Item .env.example .env

Open .env and change every value marked CHANGE ME:

Generate a random value for SECRET_KEY:

openssl rand -hex 32

Without OpenSSL, on Windows PowerShell:

$b = New-Object byte[] 32; [System.Security.Cryptography.RandomNumberGenerator]::Create().GetBytes($b); -join ($b | ForEach-Object { $_.ToString('x2') })

These settings are optional but worth setting now:

For every other setting, see Configuration.

#3. Start the stack

docker compose up -d --build

The first build takes several minutes. Compose starts these services:

Check that everything is up:

docker compose ps

vault-init exits after it finishes. That is expected. The other services should show running or healthy.

If you use make, make up does the same as steps 2 and 3. If .env does not exist, it creates one from .env.example and stops so you can edit it.

#4. Find the one-time password

On the first start, the API creates your organization, the built-in roles, a project named Default and the first admin user. If BOOTSTRAP_ADMIN_PASSWORD is empty, it prints a random one-time password in its log:

docker compose logs api | grep -A3 "OpsNexus is ready"

On Windows PowerShell:

docker compose logs api | Select-String -Context 0,3 "OpsNexus is ready"

The output looks like this:

================================================================
 OpsNexus is ready. Organization: Acme Corp  (Account ID: acme-corp-1234)
 Sign in as: admin@example.com
 One-time password: <random value>   <- change it after signing in
================================================================

The password is printed only once, on the first start. It stays in the log until the api container is recreated. If you lose it on a fresh install that holds no data yet, run docker compose down -v to delete the volumes, set BOOTSTRAP_ADMIN_PASSWORD in .env, and start again.

#5. Sign in

1. Open http://localhost:8080 (or your PUBLIC_URL).
2. In Email or username, enter the admin email, or the username admin.
3. Enter the one-time password and select Sign in.

#6. Change the password and turn on MFA

1. In the sidebar, under Settings, open Password, MFA & SSO.
2. In Your password, enter the one-time password as Current password, choose a New password, and select Change password.
3. In Multi-factor authentication, select Set up MFA.
4. Scan the QR code with an authenticator app, such as Google Authenticator, Microsoft Authenticator or 1Password.
5. Enter the 6-digit code and select Turn on MFA.

From now on, sign-in asks for a code from your authenticator app after your password.

#7. Check the system status

Open Settings → System status. It shows the health of the database, the cache and queue, the secret store and the background workers. All four should be OK.

The API reference (OpenAPI) is at http://localhost:8080/api/docs.

#Next steps

1. Connect your tools. Go to CI/CD → Integrations and select Connect a tool to import pipelines from Jenkins, GitLab, Azure DevOps, Argo CD or GitHub Actions. See Integrations.
2. Add a build agent. Go to Build agents and select Download & install. See Build agents.
3. Create your first pipeline. See Pipelines.
4. Connect a cloud account. See Cloud accounts.
5. Invite your team. Create named admin accounts and give people roles. See Access control.
6. Before going live, read Running in production.

#Stop and start

docker compose down      # stop the stack; data in volumes is kept
docker compose up -d     # start it again