# Manual install

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

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

Source: https://helpdesk.orangescrum.com/guide/community/install/manual

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

> **Note**
>
> [Docker](https://helpdesk.orangescrum.com/guide/community/install/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](https://helpdesk.orangescrum.com/guide/community/get-started/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](https://helpdesk.orangescrum.com/guide/community/install/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;
    }
}
```

```apache
<VirtualHost *:80>
    ServerName orangescrum.example.com
    DocumentRoot /var/www/orangescrum/webroot

    <Directory /var/www/orangescrum/webroot>
        Options -Indexes +FollowSymLinks
        AllowOverride All
        Require all granted
    </Directory>

    ErrorLog  ${APACHE_LOG_DIR}/orangescrum-error.log
    CustomLog ${APACHE_LOG_DIR}/orangescrum-access.log combined
</VirtualHost>
```

    `mod_rewrite` must be enabled:

```bash
sudo a2enmod rewrite && sudo systemctl restart apache2
```

## 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](https://helpdesk.orangescrum.com/guide/community/install/configuration).

- [Next: the install wizard](https://helpdesk.orangescrum.com/guide/community/install/install-wizard): Create the schema and your admin account.