# Install wizard

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

> For the complete documentation index, see [llms.txt](https://helpdesk.orangescrum.com/llms.txt).

Source: https://helpdesk.orangescrum.com/guide/community/install/install-wizard

---
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

**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.

**Database configuration**

    Enter your PostgreSQL connection details:

    | Field | Docker default |
    | --- | --- |
    | Host | `orangescrum-postgres` |
    | Port | `5432` |
    | Database | `orangescrum` |
    | Username | `orangescrum` |
    | Password | `orangescrum` |

    The connection is tested before you can proceed.

**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.

**Seed data**

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

**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](https://helpdesk.orangescrum.com/guide/community/install/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](https://helpdesk.orangescrum.com/guide/community/install/configuration): Mail, base URL, sessions and the settings to change before going live.