Start free

For AI agents: a documentation index is available at /llms.txt. A markdown version of this page is available at /guide/community/install/install-wizard.md.

CommunityInstall

Install wizard

The browser-based installer that creates the schema, seeds defaults and sets up your admin account.

On first visit, a fresh instance redirects to the install wizard. It checks the environment, creates the database schema, seeds default data and hands you a working workspace.

No licence step

The Community Edition is licence-free. There is no key to enter, no email to register and no phone-home check — the licence step present in the commercial installer is skipped entirely.

#What it does

  1. System requirements check

    Verifies the PHP version, the required extensions and that config/, tmp/ and logs/ are writable. Fix anything flagged here before continuing — later steps assume it passed.

  2. Database configuration

    Enter your PostgreSQL connection details:

    FieldDocker default
    Hostorangescrum-postgres
    Port5432
    Databaseorangescrum
    Usernameorangescrum
    Passwordorangescrum

    The connection is tested before you can proceed.

  3. Schema creation

    Runs the migrations that create the tables, then drops the tables belonging to features the Community Edition does not ship. A finished install has roughly 149 tables.

    This is the slow step — a few minutes is normal. Do not reload the page.

  4. Seed data

    Inserts defaults: task types, statuses, priorities, roles and the initial company record.

  5. Finish

    You are redirected to sign-up, where you create the first account.

#Creating the admin account

The first account created after installation is the administrator. It can:

  • Invite and deactivate users
  • Create and archive projects
  • Change company-wide settings

Use a real address

Password resets and invitations go by email. If SMTP is not configured yet, set it up before you need to reset that password — see Configuration.

If you installed manually, you can also set the password from the CLI:

bash
php bin/cake.php change_admin_password

Or in Docker:

bash
docker compose exec orangescrum-app php bin/cake.php change_admin_password

#Verifying the install

After signing in, confirm these pages load without error:

  • The dashboard at /
  • Projects at /projects/manage
  • Tasks at /easycases/dashboard
  • Your work at /yourWorks

Then check the log is clean:

bash
docker compose exec orangescrum-app tail -50 logs/error.log

#Troubleshooting

The wizard reappears after finishing

Configuration is written to config/. If that directory is not writable, or the Docker config volume was recreated, the app cannot tell it has been installed. Check permissions, and confirm orangescrum-app-config exists.

Schema creation times out

The migration run exceeds max_execution_time. Raise it to 300 seconds and re-run. In Docker this is already configured.

Database connection failed

From the app container, the host is the service name (orangescrum-postgres), not localhost — the database is in a different container. For a manual install on the same machine, localhost is correct.

Extension missing at the requirements step

Install it and restart PHP-FPM or Apache. pdo_pgsql is the usual culprit; Orangescrum does not support MySQL.

Re-running the installer on an existing database

The installer is designed to run against an empty schema. Pointing it at a database that already has data risks conflicts — back up first, and prefer a fresh database.

⚙️Next: configuration

Mail, base URL, sessions and the settings to change before going live.