Skip to content

03 First-Time Setup in Browser

This chapter documents the first-run setup flow for SSH Teams in the browser.

Manual operator URL (interactive setup flow): https://<hostname>/setup

3.1 Prerequisites

Requirement Lab Staging Production
Reachable HTTPS hostname for SSH Teams Required Required Required
Browser trust path for certificate Optional Recommended Required
Team owner/admin identity decided Recommended Required Required
Password policy baseline defined Optional Recommended Required
Setup/legal approver identified Optional Recommended Required

3.2 Accessing the Setup UI

flowchart TD
    A[Start at root URL] --> B{Team exists}
    B -- No --> C[Redirect to /setup]
    C --> D[Complete team and admin form]
    D --> E{Validation passes}
    E -- No --> F[Show validation errors]
    F --> C
    E -- Yes --> G[Persist team and first admin]
    G --> H[Enter authenticated app flow]

    B -- Yes --> I[Redirect to /login]
    I --> J[Authenticate existing user]
    J --> H

Open the setup UI over HTTPS:

  • Setup URL: https://<hostname>/setup
  • Root URL behavior: https://<hostname>/ redirects to /setup when no team exists yet.

Expected page title:

  • SSH Teams - Initial Setup

Setup screen:

SSH Teams first-time setup full page

If setup is not shown and you land on /login, at least one team has already been created.

3.3 Creating the Primary Team and Admin

On first run, complete the Create Your Team form:

  1. Your Name: display name for the initial administrator and audit visibility.
  2. Email Address: login identifier for the initial administrator and account recovery path.
  3. Password: initial credential for privileged access; use a high-entropy value.
  4. Confirm Password: prevents accidental admin lockout due to typos.
  5. Team Name: trust-domain label shown across policy and administration surfaces.
  6. Check the terms acknowledgment checkbox.
  7. Click Create Team & Continue.

Result:

  • The primary team is created.
  • The first admin user is created and associated with that team.
  • The application redirects into the normal authenticated experience.

Recommended admin values for production:

  • Use an organizational email mailbox that supports ownership transfer.
  • Use a long unique password managed by your password manager.
  • Pick a stable Team Name used by your operators.

3.4 Terms and Licensing Behavior During Setup

The setup page includes an explicit usage/terms acknowledgment block.

Key points shown to the operator:

  • Internal business use only.
  • No redistribution/resale/service-provider use.
  • Periodic activation validation against Jadaptive activation services.

Behavior:

  • If the acknowledgment checkbox is not checked, setup submission is blocked.
  • Setup remains accessible until the first team is created successfully.

Operator guidance:

  • Complete legal/internal review before production rollout.
  • Keep a record of who accepted terms during initial setup.

3.5 Post-Setup Redirect and Login Expectations

After successful setup:

  1. You are redirected away from /setup.
  2. Future requests to root (/) resolve to login/dashboard flow, not setup.
  3. Team admin can sign in with the email/password entered during setup.

Expected steady-state behavior:

  • /setup should no longer be usable for creating additional first-run teams.
  • Team/user lifecycle is managed from administration pages after login.

Quick verification checklist:

  • Login succeeds with initial admin credentials.
  • Dashboard renders.
  • Administration sections are visible to admin.

3.6 Setup Failure Modes and Recovery

Common first-run setup failure modes and actions:

  • Password mismatch:

    • Symptom: setup form rejects submission.
    • Action: ensure Password and Confirm Password are identical.

  • Terms checkbox not checked:

    • Symptom: setup form rejects submission.
    • Action: check the acknowledgment checkbox and resubmit.

  • Setup page not shown:

    • Symptom: root redirects to /login instead of /setup.
    • Action: the instance is already initialized; use admin credentials or recover data/state from persistence volumes.

  • Browser cannot load assets:

    • Symptom: page appears unstyled or icon requests fail.
    • Action: validate static asset routing and reverse-proxy MIME/type handling.

  • HTTPS/certificate warnings:

    • Symptom: browser blocks access before form submission.
    • Action: trust/install proper TLS certs for the deployment hostname.

Recovery notes:

  • In containerized deployments, first-run state is persisted in mounted data volumes.
  • To intentionally re-enter first-run mode for a lab instance, start from a clean data volume/snapshot.

3.7 First Login After Setup

After initial setup completes, normal operator access is through the team login page.

  • Login URL: https://<hostname>/login

Use the admin account created during setup:

  • Email: the value entered in setup Email Address.
  • Password: the value entered in setup Password.

Expected login screen:

SSH Teams team login page

Post-login expectation:

  • Successful sign-in redirects to dashboard.
  • If sign-in fails, verify credentials and check for caps-lock/password manager autofill issues.