Manual Installation

Step-by-step guide for all supported operating systems.

Ubuntu 22.04 / 24.04

1. Update system and install PHP

sudo apt update && sudo apt upgrade -y

# Add PHP repository
sudo add-apt-repository ppa:ondrej/php -y
sudo apt update

# Install PHP 8.3 and extensions
sudo apt install -y php8.3 php8.3-fpm php8.3-cli php8.3-mysql \
    php8.3-mbstring php8.3-xml php8.3-curl php8.3-zip php8.3-gd \
    php8.3-bcmath php8.3-intl php8.3-soap php8.3-gmp php8.3-sodium \
    php8.3-fileinfo php8.3-tokenizer php8.3-readline

2. Install MySQL and Nginx

# MySQL
sudo apt install -y mysql-server

# Nginx
sudo apt install -y nginx

# Composer
curl -sS https://getcomposer.org/installer | php
sudo mv composer.phar /usr/local/bin/composer

# Certbot (for SSL)
sudo apt install -y certbot python3-certbot-nginx

3. Create database

sudo mysql -e "CREATE DATABASE arcbilling CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;"
sudo mysql -e "CREATE USER 'arcbilling'@'localhost' IDENTIFIED BY 'YOUR_STRONG_PASSWORD';"
sudo mysql -e "GRANT ALL PRIVILEGES ON arcbilling.* TO 'arcbilling'@'localhost';"
sudo mysql -e "FLUSH PRIVILEGES;"

4. Deploy files

cd /var/www
sudo unzip /tmp/arcbilling-v*.zip
cd arcbilling

# Install dependencies
sudo composer install --no-dev --optimize-autoloader --no-interaction

# Environment
sudo cp .env.example .env
sudo nano .env   # Set APP_URL, DB_*, ARCBILLING_LICENSE_KEY

# Laravel setup
sudo php artisan key:generate
sudo php artisan storage:link

# Permissions
sudo chown -R www-data:www-data /var/www/arcbilling
sudo find /var/www/arcbilling -type f -exec chmod 644 {} \;
sudo find /var/www/arcbilling -type d -exec chmod 755 {} \;
sudo chmod -R 775 /var/www/arcbilling/storage
sudo chmod -R 775 /var/www/arcbilling/bootstrap/cache

5. Configure Nginx

sudo nano /etc/nginx/sites-available/arcbilling.conf

server {
    listen 80;
    listen [::]:80;
    server_name billing.example.com;
    root /var/www/arcbilling/public;
    index index.php;

    client_max_body_size 64M;

    add_header X-Frame-Options "SAMEORIGIN" always;
    add_header X-Content-Type-Options "nosniff" always;
    add_header X-XSS-Protection "1; mode=block" always;

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

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

    location ~ /\.(?!well-known).* {
        deny all;
    }
}

sudo ln -s /etc/nginx/sites-available/arcbilling.conf /etc/nginx/sites-enabled/
sudo rm -f /etc/nginx/sites-enabled/default
sudo nginx -t && sudo systemctl reload nginx

6. SSL and Cron

# SSL certificate
sudo certbot --nginx -d billing.example.com

# Scheduler cron
sudo crontab -u www-data -e
# Add: * * * * * cd /var/www/arcbilling && php artisan schedule:run >> /dev/null 2>&1

Debian 11 / 12

1. Update system and install PHP (Sury)

sudo apt update && sudo apt upgrade -y

# Add Sury PHP repository
sudo apt install -y lsb-release gnupg2 curl
curl -fsSL https://packages.sury.org/php/apt.gpg | sudo gpg --dearmor -o /usr/share/keyrings/sury-php.gpg
echo "deb [signed-by=/usr/share/keyrings/sury-php.gpg] https://packages.sury.org/php/ $(lsb_release -cs) main" \
    | sudo tee /etc/apt/sources.list.d/sury-php.list
sudo apt update

# Install PHP 8.3 + extensions
sudo apt install -y php8.3 php8.3-fpm php8.3-cli php8.3-mysql \
    php8.3-mbstring php8.3-xml php8.3-curl php8.3-zip php8.3-gd \
    php8.3-bcmath php8.3-intl php8.3-gmp php8.3-sodium php8.3-fileinfo

2. Install MySQL and Nginx

sudo apt install -y mariadb-server nginx

# Composer
curl -sS https://getcomposer.org/installer | php
sudo mv composer.phar /usr/local/bin/composer

# Certbot
sudo apt install -y certbot python3-certbot-nginx

AlmaLinux 9 / Rocky Linux 9 / CentOS Stream 9

1. Update system and install PHP (Remi)

sudo dnf update -y

# Enable EPEL and Remi repositories
sudo dnf install -y epel-release
sudo dnf install -y https://rpms.remirepo.net/enterprise/remi-release-9.rpm

# Enable PHP 8.3
sudo dnf module reset php -y
sudo dnf module enable php:remi-8.3 -y

# Install PHP and extensions
sudo dnf install -y php php-fpm php-cli php-mysqlnd php-mbstring php-xml \
    php-curl php-zip php-gd php-bcmath php-intl php-soap php-gmp \
    php-sodium php-fileinfo php-tokenizer

2. Install MySQL and Nginx

sudo dnf install -y mysql-server nginx
sudo systemctl enable --now mysqld nginx

curl -sS https://getcomposer.org/installer | php
sudo mv composer.phar /usr/local/bin/composer

sudo dnf install -y certbot python3-certbot-nginx

3. Firewall and SELinux

# Open HTTP/HTTPS ports
sudo firewall-cmd --permanent --add-service=http
sudo firewall-cmd --permanent --add-service=https
sudo firewall-cmd --reload

# Allow PHP to make network requests and send email
sudo setsebool -P httpd_can_network_connect 1
sudo setsebool -P httpd_can_sendmail 1

4. Create database

sudo mysql -e "CREATE DATABASE arcbilling CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;"
sudo mysql -e "CREATE USER 'arcbilling'@'localhost' IDENTIFIED BY 'YOUR_STRONG_PASSWORD';"
sudo mysql -e "GRANT ALL PRIVILEGES ON arcbilling.* TO 'arcbilling'@'localhost';"
sudo mysql -e "FLUSH PRIVILEGES;"

5. Deploy files

cd /var/www
sudo unzip /tmp/arcbilling-v*.zip
cd arcbilling

sudo composer install --no-dev --optimize-autoloader --no-interaction
sudo cp .env.example .env
sudo nano .env
sudo php artisan key:generate
sudo php artisan storage:link

# Permissions (nginx user)
sudo chown -R nginx:nginx /var/www/arcbilling
sudo find /var/www/arcbilling -type f -exec chmod 644 {} \;
sudo find /var/www/arcbilling -type d -exec chmod 755 {} \;
sudo chmod -R 775 /var/www/arcbilling/storage
sudo chmod -R 775 /var/www/arcbilling/bootstrap/cache

6. Configure Nginx

sudo nano /etc/nginx/conf.d/arcbilling.conf

server {
    listen 80;
    listen [::]:80;
    server_name billing.example.com;
    root /var/www/arcbilling/public;
    index index.php;

    client_max_body_size 64M;

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

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

    location ~ /\.(?!well-known).* {
        deny all;
    }
}

7. PHP-FPM

sudo sed -i 's/^user = apache/user = nginx/' /etc/php-fpm.d/www.conf
sudo sed -i 's/^group = apache/group = nginx/' /etc/php-fpm.d/www.conf
sudo systemctl restart php-fpm
sudo nginx -t && sudo systemctl reload nginx

8. SSL and Cron

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

sudo crontab -u nginx -e
# Add: * * * * * cd /var/www/arcbilling && php artisan schedule:run >> /dev/null 2>&1

Apache (Alternative)

Ubuntu / Debian

sudo apt install -y apache2 libapache2-mod-php8.3
sudo a2enmod rewrite

# /etc/apache2/sites-available/arcbilling.conf
<VirtualHost *:80>
    ServerName billing.example.com
    DocumentRoot /var/www/arcbilling/public

    <Directory /var/www/arcbilling/public>
        AllowOverride All
        Require all granted
    </Directory>

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

sudo a2ensite arcbilling.conf
sudo a2dissite 000-default
sudo systemctl reload apache2
sudo certbot --apache -d billing.example.com

AlmaLinux / Rocky / CentOS

sudo dnf install -y httpd mod_ssl
sudo systemctl enable --now httpd

# /etc/httpd/conf.d/arcbilling.conf
<VirtualHost *:80>
    ServerName billing.example.com
    DocumentRoot /var/www/arcbilling/public

    <Directory /var/www/arcbilling/public>
        AllowOverride All
        Require all granted
    </Directory>
</VirtualHost>

sudo systemctl reload httpd
sudo certbot --apache -d billing.example.com

Web Setup Wizard

https://billing.example.com/install

Step	What it does
1. Welcome	Overview and prerequisites
2. Requirements	PHP version, extensions, directory permissions
3. License	Enter your ArcBilling license key
4. Database	MySQL connection (test button included)
5. Settings	Site name, URL, timezone, language, currency
6. Admin Account	Create the admin user
7. Mail	SMTP configuration (optional, can skip)
8. Payment	Stripe / PayPal setup (optional)
9. Complete	Finalizes installation

Post-Installation Checklist

• SSL certificate installed (https:// works)
• APP_DEBUG=false in .env
• APP_ENV=production in .env
• Cron job running
• File permissions are correct (no 777)
• Database password is strong
• Admin password is strong
• Firewall configured (only 80/443 open)
• License key is activated

Troubleshooting

500 Internal Server Error

cat storage/logs/laravel.log | tail -50
php artisan config:clear && php artisan cache:clear
# Fix permissions:
sudo chown -R www-data:www-data /var/www/arcbilling  # Ubuntu/Debian
sudo chown -R nginx:nginx /var/www/arcbilling         # RHEL-based

Blank White Page

Set APP_DEBUG=true in .env temporarily, check the error, then set it back to false.

License Activation Failed

• Server must reach https://arcbilling.tech (outbound HTTPS)
• php-curl must be installed
• Verify the license key is correct
• On RHEL-based: sudo setsebool -P httpd_can_network_connect 1

SELinux Blocking PHP (RHEL-based only)

sudo setsebool -P httpd_can_network_connect 1
sudo setsebool -P httpd_can_sendmail 1
sudo restorecon -R /var/www/arcbilling