Skip to main content

Setup Wizard

The Setup Wizard is an interactive web interface that guides you through initial configuration of a self-hosted Plexicus deployment. It runs during first-boot and collects settings for licensing, services, AI, email, and optional SCM integrations, then persists them as Kubernetes secrets.

Location: After deploying Plexicus to Kubernetes, navigate to the wizard frontend (typically http://plexicus.local/setup) and complete the 7-step flow.

Overview: 7-Step Wizard Flow​

StepTitlePurposeRequiredValidation
0Welcome / System CheckVerify cluster connectivity, show derived URLs—Diagnostic only
1LicenseValidate and submit your Plexicus license JWTYesLicense signature & expiry
2ServicesMongoDB, Redis, MinIO credentialsYesConnection test (auth + connectivity)
3AI ProviderOpenAI, Azure, or OpenAI-compatible endpointYesModel list fetch + SSRF checks
4Email (SMTP)Email server credentials for notificationsYesConnection test + optional email send
5Source Control (optional)GitHub App or other SCM OAuth setupNoOAuth flow + webhook validation
6Review ConfigurationSummary of all entries before finalization—Read-only confirmation
FinalConfiguration CompleteHelm upgrade command to apply settings—Copy-paste ready

Step 0: Welcome / System Check​

What you see:

  • Derived frontend/API URLs (based on your ingress hostname)
  • Kubernetes cluster details (API server, namespace, etc.)
  • License status summary
  • List of completed steps (if resuming a prior session)

What it does:

  • Queries the setup-wizard backend for cluster hostname and derived URLs
  • Reads Kubernetes secrets to check for existing plexicus-runtime-config (if already deployed)
  • Reads progress from plexicus-setup-progress secret (to resume incomplete wizard)

No action required — just review the URLs. If the hostname or URLs are incorrect, you may need to adjust your ingress or DNS before proceeding.

tip

If URLs look wrong (e.g., showing localhost instead of your domain), verify your ingress.hosts[0].host in values.yaml.

Step 1: License​

What to provide: A valid Plexicus license JWT file (provided by your sales contact or the Plexicus backend).

To submit your license:

  1. Obtain your license JWT string (usually a long Base64-encoded token, e.g., eyJ...).
  2. Paste it into the License JWT field.
  3. Click Validate License.
  4. The wizard verifies the signature and expiry date.

What the wizard checks:

  • License signature (RSA verification)
  • Expiry date (must be in the future)
  • Plan tier (Starter, Scale, Enterprise)
  • Feature set and quotas encoded in the token

If validation fails:

  • "Invalid signature" — License JWT is corrupted or from wrong issuer
  • "License expired" — Renew your license with your account manager
  • "License not yet valid" — Check the license start date
info

Your license token is encrypted when stored in the plexicus-setup-progress Kubernetes Secret. It is never transmitted to the public internet.

After successful validation, the wizard stores the license in the progress secret and moves to Step 2.

Step 2: Services (MongoDB, Redis, MinIO)​

What to provide: Credentials for three backing services:

MongoDB​

  • Host — MongoDB server hostname or IP (e.g., mongo.default.svc.cluster.local)
  • Port — MongoDB port (usually 27017)
  • Username — Admin or application user
  • Password — User password
  • Database — Database name (usually plexicus)
  • Options (optional) — URI query string (e.g., authSource=admin&ssl=true)

Redis​

  • Host — Redis server hostname or IP
  • Port — Redis port (usually 6379)
  • Username — (optional, if AUTH required)
  • Password — (optional, if AUTH required)

MinIO (S3-Compatible Object Storage)​

  • Endpoint — MinIO server endpoint (e.g., minio.default.svc.cluster.local:9000)
  • Access Key — MinIO access key ID
  • Secret Key — MinIO secret access key
  • Bucket — S3 bucket name for scan results (e.g., plexicus-scans)
  • SSL — Toggle if MinIO uses TLS (port 9000 = no, port 9443 = yes)

To test connectivity:

Click Test Database, Test Redis, or Test MinIO for each service:

  • Establishes a connection with provided credentials
  • Validates authentication
  • Returns "Connected" or detailed error (e.g., "Authentication failed", "Connection timeout")

Common issues:

  • "Connection refused" — Service not running or wrong hostname
  • "Authentication failed" — Wrong username/password
  • "Certificate verification failed" — SSL/TLS misconfiguration on MinIO
  • "No such database" — Database doesn't exist (manually create it in MongoDB first)

If tests pass, click Save & Continue to store in the progress secret.

warning

These credentials are encrypted in the Kubernetes Secret plexicus-setup-progress. Do not expose the progress secret to untrusted users.

Step 3: AI Provider​

What to provide: Connection details for your AI service used by remediation + finding enrichment engines.

Supported Providers​

OpenAI (API Key)

  • API Key — Your OpenAI API key (starts with sk-proj-…)
  • Base URL — Leave blank (defaults to https://api.openai.com/v1)
  • Model (optional) — Model ID to use (e.g., gpt-4, gpt-4-turbo; defaults to latest available)

Azure OpenAI

  • API Key — Your Azure OpenAI API key
  • Base URL — Your Azure deployment URL (e.g., https://your-org.openai.azure.com/)
  • Deployment Name — Azure deployment ID (e.g., gpt-4-deployment)
  • API Version — Azure API version (e.g., 2024-02-15-preview)

OpenAI-Compatible (DeepInfra, DeepSeek, etc.)

  • API Key — Provider's API key
  • Base URL — Provider endpoint (e.g., https://api.deepinfra.com/openai/v1)
  • Model (optional) — Model name available at that endpoint

To test connectivity:

  1. Click Test AI Provider.
  2. The wizard fetches the available models list from your provider.
  3. If you specified a custom model, it verifies that model exists.
  4. Response: "Connected" or detailed error (e.g., "Invalid API key", "Model not found", "Connection timeout").
info

Azure URLs are checked against SSRF (Server-Side Request Forgery) patterns. Private/internal URLs (e.g., http://127.0.0.1, http://10.0.0.0/8) are rejected for security. Use only public Azure endpoints or pre-approved internal ranges configured by your cluster admin.

Important: The AI provider is used for:

  • Generating remediation code for found vulnerabilities
  • Enriching findings with context and severity assessment
  • False positive detection

Availability/cost of this provider directly impacts Plexicus functionality. Budget for API calls accordingly.

Step 4: Email (SMTP)​

What to provide: SMTP server credentials for transactional emails (password reset, team invites, scan notifications, etc.).

SMTP Configuration​

  • Host — SMTP server hostname (e.g., smtp.gmail.com, smtp.sendgrid.net)
  • Port — SMTP port (usually 587 for TLS or 465 for SSL, rarely 25)
  • Username — SMTP authentication username (often an email address)
  • Password — SMTP authentication password or API token
  • From Address — Email address that appears in the "From:" field (e.g., noreply@plexicus.ai)
  • TLS/SSL — Toggle encryption method

To test connectivity:

  1. Click Test SMTP to verify credentials and connectivity.
  2. Optionally, send a test email to your address to confirm delivery (button: Send Test Email).
  3. Response: "Connected" or detailed error (e.g., "Authentication failed", "Connection timeout", "Port blocked").

Common SMTP providers:

ProviderHostPortTLS
Gmail / Google Workspacesmtp.gmail.com587Yes
SendGridsmtp.sendgrid.net587Yes
AWS SESemail-smtp.{region}.amazonaws.com587Yes
Office 365 / Outlooksmtp.office365.com587Yes
Postfix/On-Premisemail.example.com25/587Depends
warning

Do not use an admin/personal email account. Create a dedicated service account (e.g., plexicus-notifications@company.com) with SMTP-only permissions. Rotate the password regularly.

Step 5: Source Control (Optional)​

Purpose: Register Plexicus as an OAuth app in your SCM provider(s) so users can authenticate and scan repositories.

This step is optional — you can skip it and configure SCM integrations later in the Settings UI.

If you want to use GitHub for scanning:

  1. Click Create GitHub App (or select Manual Setup if you already have an app).
  2. The wizard displays a manifest request with pre-filled fields:
    • App name: Plexicus-{yourorganization}
    • Permissions: checks:read/write, contents:read, pull_requests:read/write, webhooks:write
    • Redirect URL: Plexicus API callback endpoint
  3. Click Install App (you are redirected to GitHub).
  4. Authorize the app in GitHub; GitHub redirects back to the wizard with credentials.
  5. The wizard stores the app ID, client ID, client secret, and private key in the progress secret.
info

The GitHub App method is recommended over Personal Access Tokens because it scopes permissions narrowly and doesn't require sharing personal credentials.

Other SCM Providers​

For GitLab, Bitbucket, Gitea, or other providers:

  1. Enter the provider's OAuth credentials:
    • OAuth App ID / Client ID
    • OAuth Client Secret
    • Webhook Secret (if applicable)
  2. Click Test SCM Connection to verify OAuth flow.
note

GitLab, Bitbucket, and Gitea are configured here; Azure DevOps and TFVC are configured post-deployment via the Settings UI.

NVD API Key (Optional) If you want to scan for known vulnerabilities in dependencies, provide your NVD (National Vulnerability Database) API Key. This is optional but recommended for accurate SCA results.

Step 6: Review Configuration​

What you see: A read-only summary of all your entries:

  • License tier and expiry
  • MongoDB, Redis, MinIO hosts and credentials (masked for security)
  • AI provider endpoint (masked)
  • SMTP server (masked)
  • SCM provider status
  • NVD API key presence (yes/no)

No action required — review for accuracy. If you spot an error, click Back to re-enter any step.

Step 7 (Final): Configuration Complete​

What happens:

  1. The wizard validates all entries one final time.
  2. Creates the plexicus-runtime-config Kubernetes Secret with:
    • License JWT (encrypted)
    • MongoDB URI
    • Redis connection
    • MinIO credentials
    • AI provider config
    • SMTP settings
    • SCM OAuth credentials
    • NVD API key
  3. Deletes the plexicus-setup-progress Secret (cleanup).
  4. Displays a Helm upgrade command you must run to apply the settings:
helm upgrade plexicus plexicus/plexicus \
  --namespace plexicus \
  --values values.yaml \
  --set global.setupMode=false

To finalize:

  1. Copy the command.
  2. Run it in your terminal (on a machine with kubectl access to your cluster).
  3. Wait for the Helm upgrade to complete (~2–5 minutes).
  4. Verify rollout: 
    kubectl rollout status deployment/plexicus -n plexicus
  5. Navigate to your Plexicus frontend URL; you should see the login screen.
warning

Important: You MUST run the helm upgrade command to disable setupMode and apply the runtime config. Without it, the wizard page remains in a loop.

Resuming an Interrupted Wizard​

If the wizard is interrupted (browser closed, network timeout, etc.):

  1. Navigate back to the wizard URL (e.g., http://plexicus.local/setup).
  2. The wizard checks for the plexicus-setup-progress Secret.
  3. If found, it displays Resume Wizard — click to pick up where you left off.
  4. Your entries from previous steps are pre-filled.
info

Progress is persisted in Kubernetes, so you can safely close the browser and resume from a different device.

Troubleshooting​

"Failed to read wizard state"​

Cause: Backend cannot access Kubernetes API or plexicus-setup-progress secret.

Fix:

  1. Verify the wizard pod has RBAC permissions to read/write secrets: 
    kubectl get rolebinding -n plexicus | grep setup-wizard
  2. Check wizard pod logs: 
    kubectl logs -n plexicus deployment/setup-wizard
  3. Restart the wizard: 
    kubectl rollout restart deployment/setup-wizard -n plexicus

"License validation failed: invalid signature"​

Cause: License JWT is corrupted or from a different Plexicus environment.

Fix:

  1. Re-check the license string for copy/paste errors.
  2. Verify you're using the license for the correct environment (dev vs. prod).
  3. Contact your account manager if the license is from a different Plexicus deployment.

"Database connection refused"​

Cause: MongoDB is not reachable or credentials are wrong.

Fix:

  1. Verify MongoDB is running: 
    kubectl get pods -n plexicus -l app=mongodb
  2. Check hostname: if using a Kubernetes service, use mongodb.plexicus.svc.cluster.local:27017 (not localhost).
  3. Verify credentials: 
    kubectl exec -it -n plexicus mongodb-0 -- mongosh -u <user> -p <pass> --authenticationDatabase admin

"SMTP authentication failed"​

Cause: Wrong credentials or port.

Fix:

  1. Verify credentials match your SMTP provider's settings.
  2. Test manually from the cluster: 
    telnet smtp.example.com 587
  3. Check that TLS/SSL toggle matches your provider (587 = TLS, 465 = SSL).

"Azure OpenAI URL rejected: SSRF detected"​

Cause: URL appears to be a private/internal address.

Fix:

  1. Use your public Azure endpoint (e.g., https://your-org.openai.azure.com/).
  2. If you must use a private endpoint, contact Plexicus support to whitelist your range.

"GitHub OAuth failed: state mismatch"​

Cause: CSRF state token expired or mismatched between wizard frontend and backend.

Fix:

  1. Refresh the browser and restart Step 5.
  2. Ensure wizard backend and frontend are on the same version (restart after upgrading).
  3. Check backend logs: 
    kubectl logs -n plexicus deployment/setup-wizard | grep state

Security Best Practices​

  1. Air-gapped deployments: If your cluster is air-gapped, you cannot complete the GitHub OAuth flow or test AI/SMTP connectivity. Use manual setup after deployment.
  2. Secure credentials: All credentials in the wizard are encrypted in Kubernetes Secrets. Restrict get secret RBAC to admins only.
  3. Rotate secrets post-setup: After deployment, rotate all credentials (MongoDB password, AI API key, SMTP password) via the Settings UI.
  4. Audit wizard access: The wizard is only accessible during setupMode=true. Once disabled (after Step 7), it is unreachable.
  5. TLS for wizard: If accessing the wizard over a public network, ensure your ingress has a valid TLS certificate.

What Happens After Setup?​

Once the helm upgrade completes:

  1. Plexicus backends start up and read the plexicus-runtime-config Secret.
  2. They initialize MongoDB collections and indices.
  3. They test connections to Redis, MinIO, and the AI provider.
  4. The frontend becomes available at your ingress URL.
  5. Your license is activated; you can begin scanning.

You can now:

  • Log in with your admin email and create your first repository.
  • Configure additional SCM providers, cloud integrations, etc. via Settings.
  • Run your first scan and see results in the dashboard.

Next Steps​

After setup completes:

  1. Connect your SCM repositories
  2. Configure scans
  3. Set up compliance frameworks
  4. Invite team members
  5. Configure SSO for your team