1.2. Installation on Ubuntu

Caution

This installation guide is for demonstration purposes only. For production installation you need to change steps according to your requirements.

This section will guide you through pre-compiled demo installation of FRED on Ubuntu.

1.2.1. Demo installation script

Purpose of this demo is to provide a quick and easy way to set up installation, which allows you to try out basic functionalities of the registry. The demo installation script installs the registry the same way you would set up a regular installation, except on a single machine. Further configuration is possible, however we recommend using this demo only as a testing tool.

Minimum requirements remain the same as on production. Check the system requirements section for all information.

  • Disk space: 10 GB

  • RAM: 1 GB

  • CPU: 2 cores

We recommend using a virtual machine software such as VirtualBox or Gnome-boxes with clean installation of Ubuntu server (20.04 LTS Focal Fossa) and access it using ssh. For web applications or protocols you can configure a network bridge between your virtual machine and host pc.

1.2.1.1. Installing the demo

Prior to running the installation script we recommend reading through it, so you have an overview of steps taken during the process in case you need to debug the installation.

  1. Download the project from our GitLab: https://gitlab.nic.cz/fred/demo-install/

  2. Run the installation script under root or an account with superuser permissions

  3. Verify the installation by checking the running services. The following daemons should start automatically after the FRED was installed:

    • fred-adifd

    • fred-akmd

    • fred-logd

    • fred-msgd

    • fred-pifd

    • fred-pyfred

    • fred-rifd

    • fred-webadmin

    • fred-accifd

    • fred-backend-logger

    • fred-backend-registry

    • fred-dbifd

    • fred-rsifd

    • apache2

  4. Smoke test of an uninitialized system

    CLI utilities:

    • fred-client -v 2 returns Server ID and Return code: 2501

    • whois -h localhost whatever outputs Whoisd server version and an ERROR: 101

    • genzone_client whatever outputs error “Unknown zone requested”

    You should also be able to access main page of the following web browser utilities:

  5. Initialise the registry as described in chapter system initialization. For the demo purposes, we recommmend using the provided script that initialises a .cz zone, sets up zero price for registrations and creates one system registrar with the handle REG-TLD and EPP password passwd. Zone SOA parameters are extracted from the real DNS.

  6. Test the registrations in a zone. After the registry is initialised, you may want to try out the following commands to verify your new zone is working as intended.

    # Connect to the server via EPP and login with the specified username and password
fred-client -u REG-CZ -w passwd
# Connect + run command that will create a contact with given credentials
fred-client -u REG-CZ -w passwd -d 'create_contact TEST-CONTACT "Name Surname" email@example.com Street City 12345 CZ'
# Connect + run command that will create a set of nameservers with the contact assigned as a technical contact
fred-client -u REG-CZ -w passwd -d 'create_nsset TEST-NSSET ((ns1.test-domain.cz (111.222.111.222)),(ns2.test-domain.cz (222.111.222.111))) TEST-CONTACT'
# Create a domain with the contact as the domain owner and with the NS set
fred-client -u REG-CZ -w passwd -d 'create_domain test-domain.cz TEST-CONTACT NULL TEST-NSSET'
# Ask about the domain via the command-line whois
whois -h localhost -- test-domain.cz
# Generate a zone file and check that it contains the domain
genzone_client; cat db.cz
# Ask about the domain via WHOIS and check the response
whois -h localhost:4444 test-domain.cz
# Ask about the domain via RDAP and check the JSON response
curl -k -L https://localhost:4445/domain/test-domain.cz | json_pp

  7. The registry is ready to use. You can find the following services running on these locations:

    • Browser:
    • Protocols:
    • CLI Tools:

      • /usr/sbin/fred-admin – Administrate the registry, registrars and customise pricing (some of these actions are also available in more user friendly FERDA administration interface)

      • /usr/bin/fred-client – A Python EPP client for registrars to allow administration registry objects without having to write their own implementation of EPP

      • C++ and python daemons as described here

    • Databases: To access the db cluster switch to user postgres using sudo su - postgres and running psql

Please note that for full functionality you should configure periodic tasks, as described in chapter periodic tasks.

1.2.2. Installation steps

This section explains some of the the individual steps that are taken by the installation script to install software required for the operation of FRED. For more details check the script, which contains comments on all actions taken.

Switch to root before you begin

sudo su -

1.2.2.1. Prerequisites

  1. Install dependencies

    apt update
apt install -y ca-certificates curl gnupg lsb-release python3-dnspython

  2. Docker installation

    sudo mkdir -m 0755 -p /etc/apt/keyrings

curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --batch --yes --dearmor -o /etc/apt/keyrings/docker.gpg

echo \
  "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/ubuntu \
  $(lsb_release -cs) stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

apt update
apt install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin

  3. Create dummy network interface for docker

    cat << EOT >> /etc/netplan/01-dock.yaml
network:
  version: 2
  renderer: networkd
  bridges:
    dock:
      dhcp4: false
      dhcp6: false
      accept-ra: false
      interfaces: [ ]
      addresses:
        - 192.168.1.1/32
EOT

netplan apply

  4. Add cznic keyring for fred packages and run update with the new source list

    mkdir -p /usr/share/keyrings/
wget https://archive.nic.cz/dists/cznic-archive-keyring.gpg --output-document=/usr/share/keyrings/cznic-archive-keyring.gpg

cat << EOT >> /etc/apt/sources.list.d/fred.list
deb [signed-by=/usr/share/keyrings/cznic-archive-keyring.gpg] http://archive.nic.cz/next $(lsb_release -sc) main
EOT

apt update

  5. Postfix non-interactive installation

    debconf-set-selections <<< "postfix postfix/mailname string $(hostname)"
debconf-set-selections <<< "postfix postfix/main_mailer_type string 'Internet Site'"
apt --assume-yes install postfix

1.2.2.2. FRED installation

  1. Installation of FRED backend services (using meta package)

    apt --assume-yes install fred

  2. Set the PostgreSQL timezone to UTC

    sed -i~ -e "s/^#\?\s*timezone\s*=.*/timezone = 'UTC'/" /etc/postgresql/12/main/postgresql.conf
systemctl restart postgresql

  3. Initialization of the FRED database (schemas)

    su - postgres -c "/usr/sbin/fred-dbmanager install"

  4. Add system registrar, otherwise some of the services wont start

    /usr/sbin/fred-admin --registrar_add --handle=REG-SYSTEM --reg_name=REG-SYSTEM --organization=SYSTEM --street1=SYSTEM --city=SYSTEM --email=SYSTEM --url=SYSTEM --country=CZ --dic=12345 --no_vat --system

  5. Configuration of fred-backend-registry` and fred-backend-logger – for detail see the installation script

  6. Configuration of FRED messenger – for detail see the installation script

  7. Create and initialize FRED messenger database

    sudo -u postgres psql -c 'CREATE DATABASE messenger;'
sudo -u postgres psql -c "CREATE USER messenger WITH ENCRYPTED PASSWORD 'passwd';"
sudo -u postgres psql -c 'GRANT ALL PRIVILEGES ON DATABASE messenger TO messenger;'
MESSENGER_CONFIG=/etc/fred/messenger.conf alembic --config /etc/fred/messenger-alembic.ini upgrade head

  8. Enable secretary in uWSGI

    cp /usr/share/doc/python3-django-secretary/examples/fred-secretary.ini /etc/uwsgi/apps-available/
ln -s /etc/uwsgi/apps-available/fred-secretary.ini /etc/uwsgi/apps-enabled/fred-secretary.ini
sed -i '/\/run\/uwsgi\/fred-secretary\/socket/c\socket = \/run\/uwsgi\/app\/fred-secretary\/socket' /etc/uwsgi/apps-available/fred-secretary.ini
cp /usr/share/doc/python3-django-secretary/examples/uwsgi_secretary.py /etc/uwsgi/

  9. Setup nginx and copy secretary configuration

    apt --assume-yes install nginx
cp /usr/share/doc/python3-django-secretary/examples/secretary-nginx.conf /etc/nginx/sites-available/secretary.conf
ln -s /etc/nginx/sites-available/secretary.conf /etc/nginx/sites-enabled/secretary.conf
rm /etc/nginx/sites-enabled/default

  10. Create a folder for the uWSGI socket and static files folder for secretary

    mkdir -p /run/uwsgi/app/fred-secretary/
chown www-data:www-data /run/uwsgi/app/fred-secretary
mkdir -p /var/www/fred/
chown www-data:www-data /var/www/fred

  11. Create and initialize secretary database

    sudo -u postgres psql -c 'CREATE DATABASE secretary;'
sudo -u postgres psql -c "CREATE USER secretary WITH ENCRYPTED PASSWORD 'passwd';"
sudo -u postgres psql -c 'GRANT ALL PRIVILEGES ON DATABASE secretary TO secretary;'
sudo -u www-data PYTHONPATH=/etc/fred DJANGO_SETTINGS_MODULE=secretary_cfg.settings django-admin migrate

  12. Collect secretary static files and create secretary superuser

    sudo -u www-data PYTHONPATH=/etc/fred DJANGO_SETTINGS_MODULE=secretary_cfg.settings django-admin collectstatic
sudo -u www-data DJANGO_SUPERUSER_USERNAME=admin DJANGO_SUPERUSER_PASSWORD=password DJANGO_SUPERUSER_EMAIL=admin@admin.com PYTHONPATH=/etc/fred DJANGO_SETTINGS_MODULE=secretary_cfg.settings django-admin createsuperuser --noinput

  13. Load secretary templates

    apt install python3-docopt
cd /usr/share/doc/python3-django-secretary/examples/secretary-templates/
sudo -u www-data PYTHONPATH=/etc/fred DJANGO_SETTINGS_MODULE=secretary_cfg.settings python3 load_templates.py pdf-templates.yml
sudo -u www-data PYTHONPATH=/etc/fred DJANGO_SETTINGS_MODULE=secretary_cfg.settings python3 load_templates.py fred-migration.yml
sudo -u www-data PYTHONPATH=/etc/fred DJANGO_SETTINGS_MODULE=secretary_cfg.settings python3 load_templates.py fred-templates.yml

  14. Enable installed services and start them

    systemctl enable --now omniorb4-nameserver fred-accifd fred-adifd fred-akmd fred-backend-logger fred-backend-registry fred-dbifd fred-logd fred-msgd fred-pifd fred-rifd fred-rsifd fred-pyfred fred-webadmin fred-secretary fred-messenger-server apache2 nginx

  15. Allow epp and whois daemon in apache

    a2ensite 02-fred-mod-eppd-apache.conf
a2ensite 02-fred-mod-whoisd-apache.conf
service apache2 restart

  16. Restart the nginx and services to be sure, that the config is correctly loaded

    systemctl restart nginx
systemctl restart 'fred-*'
systemctl restart omniorb4-nameserver

  17. Deploy docker apps – Ferda, Webwhois, RDAP

    apps=("ferda" "webwhois" "rdap")
WORKDIR=/etc/fred/docker-apps/
# Initialize new docker swarm so we can have docker stack for each service
docker swarm init --advertise-addr 127.0.0.1

mkdir -p $WORKDIR
# We are doing the same process for every docker app - pull demo compose and .env file, pull images and deploy them using docker stack
for app in ${apps[@]}; do
      # Create directory structure for docker-apps and download demo-deploy files
      mkdir $WORKDIR/$app-git
      cd $WORKDIR/$app-git
      git clone https://gitlab.nic.cz/fred/$app
      cd ..
      mkdir -p $WORKDIR/$app
      cp -r $app-git/$app/docs/demo-deploy $app
      rm -rf $app-git

      # Pull app images from registry.nic.cz
      docker pull registry.nic.cz/fred/$app/$app-uwsgi
      docker pull registry.nic.cz/fred/$app/$app-nginx

      # Deploy docker stacks
      cd $WORKDIR/$app/demo-deploy/
      docker stack deploy --compose-file docker-compose.yml $app
done

  18. Before starting FRED for the first time, set the timezone in PostgreSQL to your location (FRED demo script sets it automatically to UTC)

  19. Initialize the system – instructions how to do it can be found in the chapter System initialization