Manual install

Run the Community Edition directly on PHP, PostgreSQL and Apache or Nginx.

If you would rather not use Docker — or you are deploying onto existing infrastructure — the application runs as an ordinary CakePHP project.

Note

Docker is the supported path and gets you a known-good PHP build. Choose manual only if you have a reason to.

#Before you start

Confirm the host meets the requirements: PHP 8.2+, PostgreSQL 12+, Composer, and the extension list.

bash

php -v
php -m | grep -E "pdo_pgsql|mbstring|intl|openssl|tokenizer|json|xml|ctype|curl|gd|zip"
psql --version
composer --version

#Install

Get the source

bash

git clone https://github.com/Orangescrum/orangescrum.git
cd orangescrum

Install PHP dependencies

bash

composer install --no-dev --optimize-autoloader

Build front-end assets
bash
```
npm install
npm run build
```

Create the database

bash

sudo -u postgres createuser --pwprompt orangescrum
sudo -u postgres createdb --owner=orangescrum orangescrum

Note the credentials — the installer asks for them.

Set file permissions

The web server user needs to write to tmp/, logs/, config/ and the attachment directory:

bash

sudo chown -R www-data:www-data /var/www/orangescrum
sudo chmod -R 755 /var/www/orangescrum
sudo chmod -R 775 /var/www/orangescrum/tmp \
                  /var/www/orangescrum/logs \
                  /var/www/orangescrum/config \
                  /var/www/orangescrum/webroot/files

Warning

config/ must stay writable — the installer writes the generated database configuration there. A read-only config/ fails late, after the schema has already been created.

Point the web server at webroot/
The document root is webroot/, not the project root. Everything above it must be unreachable over HTTP.
Run the installer
Open your site in a browser. Continue with Install wizard.

#Web server configuration

nginx

server {
    listen 80;
    server_name orangescrum.example.com;
    root /var/www/orangescrum/webroot;
    index index.php;

    client_max_body_size 64M;

    location / {
        try_files $uri $uri/ /index.php?$args;
    }

    location ~ \.php$ {
        include fastcgi_params;
        fastcgi_pass unix:/run/php/php8.2-fpm.sock;
        fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
    }

    # Never serve the application source.
    location ~ ^/(config|src|vendor|tests|logs|tmp)/ {
        deny all;
    }
}

#PHP settings

Defaults are too tight for file uploads and the installer's migration run:

ini

memory_limit = 256M
upload_max_filesize = 64M
post_max_size = 64M
max_execution_time = 300

#After installing

bash

# Clear caches after any config change
php bin/cake.php cache clear_all

# Set the admin password
php bin/cake.php change_admin_password

#TLS

Anything beyond local testing should be behind HTTPS. With Certbot:

bash

sudo certbot --nginx -d orangescrum.example.com

Then set SESSION_COOKIE_SECURE to true and update FULL_BASE_URL to the https:// address — see Configuration.

🧙Next: the install wizard

Create the schema and your admin account.