# Install

> The guided browser installer — licence check, requirements, database and first admin account.

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

Source: https://helpdesk.orangescrum.com/guide/self-hosted/install/installer

---
Orangescrum installs through a **guided browser wizard**. It is a one-time task
for whoever deploys the server.

## Run the installer

**Open the installer**

    Browse to `http://your-domain/install` on the new server. The first person to
    load it walks through the wizard once; everyone else just gets the login page
    afterwards.

**Verify your licence**

    Enter your licence email. The installer validates it and stores the key with
    your instance.

> **This step needs outbound internet access**
>
> Licence validation calls Orangescrum. On a restricted network, allow it
> before you start — see [Licence](https://helpdesk.orangescrum.com/guide/self-hosted/admin/licence).

**Pass the requirements check**

    The wizard checks the PHP version, required extensions, file permissions and
    database connectivity, and flags anything missing. Fix what it reports before
    continuing — later steps assume this passed.

    `pdo_pgsql` is the extension people most often lack. Orangescrum runs on
    PostgreSQL only; a host with `pdo_mysql` and no `pdo_pgsql` fails here.

**Configure the database**

    Supply the PostgreSQL host, port, database name, user and password. The
    connection is tested before you can proceed.

    From inside a container the host is the **service name**
    (`orangescrum-postgresdb`), not `localhost`.

**Configure SMTP**

    Mail is set during installation. Get this right now — invitations and
    password resets depend on it, and changing it later means editing a server
    config file rather than a settings page.

**Run the install**

    The installer creates the database tables and loads the default seed data.
    This is the slow step; do not reload the page.

**Finish up**

    Clear the application cache and set the administrator password using the
    provided console commands, then log in.

```bash
php bin/cake.php cache clear_all
php bin/cake.php change_admin_password
```

    In Docker:

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

## Verify the install

Sign in and confirm the core pages load, then check the log is clean:

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

Also confirm the stack is healthy and both services answer:

```bash
docker compose ps
curl -f http://localhost:8080     # application
curl -f http://localhost:8088     # Advanced Dashboard (Superset)
```

> **Reports come up last**
>
> `orangescrum-reports` waits for its database to be healthy. Give it 60 seconds
> before treating a not-yet-ready reports service as a failure.

## Troubleshooting the install

**The installer reappears after finishing**

    Installed state is written into `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 the `app-config` volume exists.

**Requirements check fails on an extension**

    Install it and restart PHP-FPM or Apache. `pdo_pgsql` is the usual one.

**Database connection refused**

    In containers the host is the service name, not `localhost`. Confirm the
    database is healthy first — `docker compose ps`.

**Schema creation times out**

    The migration run exceeds `max_execution_time`. Raise it to 300 seconds and
    re-run.

**Licence validation fails**

    Check outbound internet access and that the licence email is exactly the one
    issued to you. Contact support@orangescrum.com if it still rejects.

## Don't stop here

An install is not finished until it is reachable over TLS, sending mail, and
backed up:

- [Configuration](https://helpdesk.orangescrum.com/guide/self-hosted/install/configuration): Domain, TLS, firewall and mail.

- [Backup](https://helpdesk.orangescrum.com/guide/self-hosted/operate/backup): Set this up before there is data worth losing.