Install

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

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

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

Domain, TLS, firewall and mail.

💾Backup

Set this up before there is data worth losing.