Skip to content

install-fossbilling.md

Latest commit

 

History

History
610 lines (437 loc) · 17.5 KB

install-fossbilling.md

File metadata and controls

610 lines (437 loc) · 17.5 KB

Namingo Registrar: Installation Guide (FOSSBilling)

This guide is for setting up FOSSBilling 0.7.2 with PHP 8.3 on Ubuntu 22.04 / 24.04 or Debian 12 / 13.

1. Install the required packages:

Follow the instructions for your operating system.

Ubuntu 22.04 / 24.04

apt update
apt install -y curl software-properties-common ufw

add-apt-repository -y ppa:ondrej/php
add-apt-repository -y ppa:ondrej/nginx
apt update

apt install -y \
  bzip2 certbot composer git net-tools unzip wget whois \
  nginx python3-certbot-nginx \
  php8.3-cli php8.3-common php8.3-curl php8.3-fpm \
  php8.3-bcmath php8.3-bz2 php8.3-gmp php8.3-intl \
  php8.3-mbstring php8.3-xml php8.3-zip php8.3-imap \
  php8.3-swoole php8.3-yaml php8.3-mysql

Debian 12 / 13

apt update
apt install -y ca-certificates curl gnupg lsb-release ufw

# PHP (SURY repo)
curl -fsSL https://packages.sury.org/php/apt.gpg \
 | 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 -sc) main" \
 > /etc/apt/sources.list.d/sury-php.list

# Nginx (official repo)
curl -fsSL https://nginx.org/keys/nginx_signing.key \
 | gpg --dearmor -o /usr/share/keyrings/nginx.gpg

echo "deb [signed-by=/usr/share/keyrings/nginx.gpg] http://nginx.org/packages/mainline/debian $(lsb_release -sc) nginx" \
 > /etc/apt/sources.list.d/nginx.list

apt update

apt install -y \
  bzip2 certbot composer git net-tools unzip wget whois \
  nginx python3-certbot-nginx \
  php8.3-cli php8.3-common php8.3-curl php8.3-fpm \
  php8.3-bcmath php8.3-bz2 php8.3-gmp php8.3-intl \
  php8.3-mbstring php8.3-xml php8.3-zip php8.3-imap \
  php8.3-swoole php8.3-yaml php8.3-mysql

1.1. Configure PHP Settings:

  1. Open the PHP-FPM configuration file:
nano /etc/php/8.3/fpm/php.ini

Add or uncomment the following session security settings:

session.cookie_secure = 1
session.cookie_httponly = 1
session.cookie_samesite = "Strict"
  1. Restart PHP-FPM to apply the changes:
systemctl restart php8.3-fpm

1.2. Configure Nginx:

Replace %%DOMAIN%% with your actual domain.

  1. Edit and save the provided configuration as /etc/nginx/sites-available/fossbilling.conf:
server {
    listen 80;
    server_name %%DOMAIN%%;
    return 301 https://%%DOMAIN%%/request_uri/;
}

server {
    listen 443 ssl http2;
    ssl_certificate      /etc/letsencrypt/live/%%DOMAIN%%/fullchain.pem;
    ssl_certificate_key  /etc/letsencrypt/live/%%DOMAIN%%/privkey.pem;
    ssl_stapling on;
    ssl_stapling_verify on;

    set $root_path '%%SOURCE_PATH%%';
    server_name %%DOMAIN%%;

    index index.php;
    root $root_path;
    try_files $uri $uri/ @rewrite;
    sendfile off;
    include /etc/nginx/mime.types;

    # Block access to sensitive files and return 404 to make it indistinguishable from a missing file
    location ~* .(ini|sh|inc|bak|twig|sql)$ {
        return 404;
    }

    # Block access to hidden files except .well-known
    location ~ /\.(?!well-known\/) {
        return 404;
    }

    # Disable PHP execution in /uploads
    location ~* /uploads/.*\.php$ {
        return 404;
    }

    # Deny access to /data
    location ~* /data/ {
        return 404;
    }

    location @rewrite {
        rewrite ^/page/(.*)$ /index.php?_url=/custompages/$1;
        rewrite ^/(.*)$ /index.php?_url=/$1;
    }

    location ~ \.php {
        fastcgi_split_path_info ^(.+\.php)(/.+)$;

        # fastcgi_pass need to be changed according your server setup:
        # phpx.x is your server setup
        # examples: /var/run/phpx.x-fpm.sock, /var/run/php/phpx.x-fpm.sock or /run/php/phpx.x-fpm.sock are all valid options
        # Or even localhost:port (Default 9000 will work fine)
        # Please check your server setup

        fastcgi_pass unix:/run/php/php8.3-fpm.sock;
            fastcgi_param PATH_INFO       $fastcgi_path_info;
            fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
            fastcgi_intercept_errors on;
            include fastcgi_params;
        }

        location ~* ^/(css|img|js|flv|swf|download)/(.+)$ {
            root $root_path;
            expires off;
        }
}
  1. Edit and save the provided configuration as /etc/nginx/sites-available/rdap.conf:
server {
    listen 80;
    listen [::]:80;
    server_name rdap.%%DOMAIN%%;

    return 301 https://$host$request_uri;
}

server {
    listen 443 ssl http2;
    listen [::]:443 ssl http2;
    server_name rdap.%%DOMAIN%%;

    ssl_certificate /etc/letsencrypt/live/%%DOMAIN%%/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/%%DOMAIN%%/privkey.pem;

    location / {
        proxy_pass http://127.0.0.1:7500;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;

        # Add CORS headers
        add_header Access-Control-Allow-Origin "*";
        add_header Access-Control-Allow-Methods "GET, OPTIONS";
        add_header Access-Control-Allow-Headers "Content-Type";

        add_header Strict-Transport-Security "max-age=31536000; includeSubDomains" always;
        
        # Enable Gzip compression
        gzip on;
        gzip_vary on;
        gzip_proxied any;
        gzip_comp_level 6;
        gzip_min_length 512;
        gzip_types
            application/json
            application/rdap+json
            text/plain
            text/css
            application/javascript
            application/xml;
    }
}
  1. Create symbolic links:
ln -s /etc/nginx/sites-available/fossbilling.conf /etc/nginx/sites-enabled/
ln -s /etc/nginx/sites-available/rdap.conf /etc/nginx/sites-enabled/
  1. Remove the default configuration if exists:
rm /etc/nginx/sites-enabled/default
  1. Obtain SSL certificate with Certbot:

Replace %%DOMAIN%% with your actual domain:

ufw disable
systemctl stop nginx
certbot certonly -d %%DOMAIN%% -d rdap.%%DOMAIN%%
certbot --nginx -d %%DOMAIN%% -d rdap.%%DOMAIN%%

Choose reinstall on the last option.

  1. Enable and restart Nginx:
systemctl enable nginx
systemctl restart nginx

2. Install and configure MariaDB:

curl -o /etc/apt/keyrings/mariadb-keyring.pgp 'https://mariadb.org/mariadb_release_signing_key.pgp'

Create /etc/apt/sources.list.d/mariadb.sources according to your system.

Ubuntu 22.04 (Jammy)

X-Repolib-Name: MariaDB
Types: deb
URIs: https://mirror.nextlayer.at/mariadb/repo/11.rolling/ubuntu
Suites: jammy
Components: main
Signed-By: /etc/apt/keyrings/mariadb-keyring.pgp

Ubuntu 24.04 (Noble)

X-Repolib-Name: MariaDB
Types: deb
URIs: https://mirror.nextlayer.at/mariadb/repo/11.rolling/ubuntu
Suites: noble
Components: main
Signed-By: /etc/apt/keyrings/mariadb-keyring.pgp

Debian 12 (Bookworm)

X-Repolib-Name: MariaDB
Types: deb
URIs: https://mirror.nextlayer.at/mariadb/repo/11.rolling/debian
Suites: bookworm
Components: main
Signed-By: /etc/apt/keyrings/mariadb-keyring.pgp

Debian 13 (Trixie)

X-Repolib-Name: MariaDB
Types: deb
URIs: https://mirror.nextlayer.at/mariadb/repo/11.rolling/debian
Suites: trixie
Components: main
Signed-By: /etc/apt/keyrings/mariadb-keyring.pgp

Then execute the following commands:

apt update
apt install -y mariadb-client mariadb-server php8.3-mysql
mariadb-secure-installation

Configuration:

  1. Access MariaDB:
mariadb -u root -p
  1. Execute the following queries:
CREATE DATABASE registrar;
CREATE USER 'registraruser'@'localhost' IDENTIFIED BY 'RANDOM_STRONG_PASSWORD';
GRANT ALL PRIVILEGES ON registrar.* TO 'registraruser'@'localhost';
FLUSH PRIVILEGES;

Replace registraruser with your desired username and RANDOM_STRONG_PASSWORD with a secure password of your choice.

Tune your MariaDB

3. Install Adminer:

wget "http://www.adminer.org/latest.php" -O /var/www/adm.php

4. Download and Extract FOSSBilling:

cd /tmp
wget https://fossbilling.org/downloads/stable -O fossbilling.zip
unzip fossbilling.zip -d /var/www

5. Make Directories Writable:

chmod -R 755 /var/www/config-sample.php
chmod -R 755 /var/www/data/cache
mkdir -p /var/www/data/log/event
chown www-data:www-data /var/www/data/cache
chmod -R 755 /var/www/data/log
chown www-data:www-data /var/www/data/log
chown www-data:www-data /var/www/data/log/event
chmod -R 755 /var/www/data/uploads
chown www-data:www-data /var/www/data/uploads
chown -R www-data:www-data /var/www

6. FOSSBilling Installation:

Proceed with the installation as prompted on https://%%DOMAIN%%. If the installer stops without any feedback, navigate to https://%%DOMAIN%%/admin in your web browser and try to log in.

7. Installing Theme:

Clone the tide theme repository:

git clone https://github.com/getpinga/tide /var/www/themes/tide
chmod 755 /var/www/themes/tide/assets
chmod 755 /var/www/themes/tide/config/settings_data.json
chown www-data:www-data /var/www/themes/tide/assets
chown www-data:www-data /var/www/themes/tide/config/settings_data.json

Activate the Tide theme from the admin panel, System -> Settings -> Theme, by clicking on "Set as default".

8. Configure FOSSBilling Settings:

Ensure you make all contact details/profile mandatory for your users within the FOSSBilling settings or configuration.

9. Additional Tools:

Clone the repository to your system:

git clone --branch v1.1.6 --single-branch https://github.com/getnamingo/registrar /opt/registrar
mkdir /var/log/namingo
mkdir /opt/registrar/escrow

10. Setup WHOIS:

cd /opt/registrar/whois
composer install
mv config.php.dist config.php

Edit the config.php with the appropriate database details and preferences as required.

Copy whois.service to /etc/systemd/system/. Change only User and Group lines to your user and group.

systemctl daemon-reload
systemctl start whois.service
systemctl enable whois.service

After that you can manage WHOIS via systemctl as any other service.

11. Setup RDAP:

cd /opt/registrar/rdap
composer install
mv config.php.dist config.php

Edit the config.php with the appropriate database details and preferences as required.

Copy rdap.service to /etc/systemd/system/. Change only User and Group lines to your user and group.

systemctl daemon-reload
systemctl start rdap.service
systemctl enable rdap.service

After that you can manage RDAP via systemctl as any other service.

12. Setup Automation Scripts:

cd /opt/registrar/automation
composer install
mv config.php.dist config.php

Edit the config.php with the appropriate preferences as required.

Download and initiate the escrow RDE client setup:

wget https://team-escrow.gitlab.io/escrow-rde-client/releases/escrow-rde-client-v2.3.1-linux_x86_64.tar.gz
tar -xzf escrow-rde-client-v2.3.1-linux_x86_64.tar.gz
mv escrow-rde-client-v2.3.1-linux_x86_64 escrow-rde-client
rm escrow-rde-client-v2.3.1-linux_x86_64.tar.gz

12.1. Submitting the Header Mapping File:

To comply with ICANN Registrar Data Escrow (RDE) Specification, you must submit your Header Mapping File to both DENIC (your DEA) and ICANN.

Step 1: Upload to DENIC

  1. Visit the DENIC escrow portal:
    https://escrow.denic-services.de/icann-header-mapping

  2. Log in with your credentials.

  3. Upload your Header Mapping File in CSV format.
    Use the structure below:

    ICANN RDE Spec,Field Name,Abbreviation
8.1.1,domain,domainname
8.1.2,expiration-date,expire
8.1.3,iana,ianaid
8.1.4,rt-name,rt-name
8.1.5,rt-street,rt-street
8.1.6,rt-city,rt-city
8.1.7,rt-state,rt-state
8.1.8,rt-zip,rt-zip
8.1.9,rt-country,rt-country
8.1.10,rt-phone,rt-phone
8.1.11,rt-email,rt-mail
3.4.1.3,bc-name,bc-name

  4. Confirm the upload was successful.

Step 2: Send to ICANN

Email the same file to ICANN at:
📧 registrar@icann.org

Include your registrar name and IANA ID in the email subject or body to help them identify your submission.

After submitting to both DENIC and ICANN, you can proceed with regular data escrow deposit generation.

12.2. Running the Automation System:

Once you have successfully configured all automation scripts, you are ready to initiate the automation system. Proceed by adding the following cron job to the system crontab using crontab -e:

* * * * * /usr/bin/php8.3 /opt/registrar/automation/cron.php 1>> /dev/null 2>&1

13. ICANN Registrar Module:

git clone https://github.com/getnamingo/fossbilling-registrar
mv fossbilling-registrar/Registrar /var/www/modules/
  • Go to Extensions > Overview in the admin panel and activate "ICANN Registrar Accreditation".

14. Domain Contact Verification:

git clone https://github.com/getnamingo/fossbilling-validation
mv fossbilling-validation/Validation /var/www/modules/
  • Go to Extensions > Overview in the admin panel and activate "Domain Contact Verification".

15. TMCH Claims Notice Support:

git clone https://github.com/getnamingo/fossbilling-tmch
mv fossbilling-tmch/Tmch /var/www/modules/

  • Go to Extensions > Overview in the admin panel and activate "TMCH Claims Notice Support".

  • Still this needs to be integrated with your workflow.

16. WHOIS & RDAP Client:

git clone https://github.com/getnamingo/fossbilling-whois
mv fossbilling-whois/Whois /var/www/modules/
mv fossbilling-whois/check.php /var/www/

  • Go to Extensions > Overview in the admin panel and activate "WHOIS & RDAP Client".

  • Edit the /var/www/check.php file and set your WHOIS and RDAP server URLs by replacing the placeholder values with your actual server addresses.

17. Domain Registrant Contact:

git clone https://github.com/getnamingo/fossbilling-contact
mv fossbilling-contact/Contact /var/www/modules/
  • Go to Extensions > Overview in the admin panel and activate "Domain Registrant Contact".

18. Installing FOSSBilling EPP Registrar Module:

For every registry backend your registrar wants to support, you need a separate installation of the FOSSBilling EPP Registrar module. Each module can handle one or more TLDs that share the same configuration details.

To configure a TLD using the Namingo FOSSBilling EPP module, follow these steps:

  1. Use our Module Customizer Tool to generate a fine-tuned EPP registrar module specifically for your registry.

  2. Extract the generated archive (as produced by the Module Customizer Tool) into /tmp

  3. Move the namingo directory and the synchronization script YourRegistryNameSync.php in the main [FOSSBilling] directory. Then place your key.pem and cert.pem files there too.

  4. Move the main module file YourRegistryName.php into the [FOSSBilling]/library/Registrar/Adapter directory.

  5. Set up a cron job that runs the sync module twice a day. Open crontab using the command crontab -e in your terminal.

Add the following cron job:

0 0,12 * * * php /var/www/html/YourRegistryNameSync.php

This command schedules the synchronization script to run once every 12 hours (at midnight and noon).

18.1. Module Activation

  1. Within FOSSBilling, go to System -> Domain Registration -> New Domain Registrar and activate the new domain registrar.

  2. Head to the "Registrars" tab. Here, you'll need to enter your specific configuration details, including the path to your SSL certificate and key. If you are configuring a gTLD, make sure to enable "Enable Minimum Data Set" in the module settings.

  3. Add a new Top Level Domain (TLD) using your module from the "New Top Level Domain" tab. Make sure to configure all necessary details, such as pricing, within this tab.

18.2. Executing OT&E Tests:

To execute the required OT&E tests by various registries, you can use our EPP client at https://github.com/getnamingo/epp-client

19. Installing FOSSBilling DNS Hosting Extensions:

To offer DNS hosting to your customers, you will need to install the FOSSBilling DNS Hosting extension.

Navigate to https://github.com/getnamingo/fossbilling-dns and follow the installation instructions.

20. Further Settings:

  1. Footer Compliance Links
    Your website footer must include links to all required ICANN documents, as well as your own Terms and Conditions and Privacy Policy.

  2. Company Information on Contact Page
    Your Contact page must clearly display your full company details, including:

    • Legal company name
    • Registration number
    • Registered address
    • Name of the Chief Executive Officer (CEO)

  3. If you experience issues saving any configuration options in the admin panel, enable the Error Reporting option to help identify the problem.

  4. ICANN MoSAPI Monitoring
    MoSAPI is ICANN’s official platform for monitoring registrar compliance and domain abuse reports.

    To enable MoSAPI support, install the Namingo MoSAPI Monitor module:

git clone https://github.com/getnamingo/fossbilling-mosapi-monitor
mv fossbilling-mosapi-monitor/Mosapimonitor /var/www/modules/

Navigate to Extensions → Overview in the FOSSBilling admin area and enable "ICANN MoSAPI Monitor".

Once activated, configure your MoSAPI credentials under System → Settings, then view registrar status and METRICA data via the Extensions menu.

  1. Backup Update your database details in automation/backup.json (in both required sections) and confirm that the cron.php cronjob is active to automate backups.