pgAdmin 4 on FreeBSD 14

Intro

This describes how to install, configure, and run pgAdmin 4 8.1 8.11 8.12 on FreeBSD 14 using mod_wsgi and the Apache webserver. On FreeBSD 13, I was able to install pgAdmin 4 by simply executing pip install pgadmin4 (in a venv), but was not able to install any version greater than 6.21 using this simple method. This does not work for me on FreeBSD 14 at all. Thus, I used the pgAdmin 4 source code.

Installation

  1. As long as you want to use pgAdmin 4, you have to have these packages installed: 
    # pkg install python ap24-py311-mod_wsgi postgresql16-client py311-sqlite3
    This also pulls in Python 3.9 and Apache 2.4. Alternatively, you can install these packages from ports, which allows you to control build options and to use latest versions.
  2. While installing pgAdmin 4, you will need these packages: 
    # pkg install rust gcc nasm node yarn gmake git libtool automake autoconf pkgconf
    You may remove them afterwards.
  3. We are using a venv to keep our base Python installation clean and tidy: 
    # python -m venv /usr/local/www/pgadmin4
  4. Download and extract latest version of pgAdmin 4: 
    # cd /usr/local/www/pgadmin4
# fetch https://ftp.postgresql.org/pub/pgadmin/pgadmin4/v8.12/source/pgadmin4-8.12.tar.gz
# tar xf pgadmin4-8.12.tar.gz
  5. Activate the venv before you compile and install inside the directory created by tar -xf: 
    # . bin/activate
# cd pgadmin4-8.12
# chown -R root:wheel .
# chmod -R go-w .
  6. Clear any files previously cached by yarn, e.g. either 
    # rm -r /usr/local/share/.cache/yarn
    or 
    # rm -r /usr/local/share/.cache
  7. Workaround for gmake bundle (see next step): 
    # git init
# git add README.md
# git commit -a -m workaround
  8. Now, we will loosely follow the official steps as noted in the file README.md: 
    # pip install -r requirements.txt
# gmake install-node
# gmake bundle
    The above steps take around 10 minutes, depending on your computer's speed and your Internet connection.
  9. Optionally, remove all cached Python packages: 
    # pip cache purge
  10. You may uninstall these software packages, as they are no longer needed: 
    # pkg delete rust gcc nasm node yarn gmake git libtool automake autoconf pkgconf
# pkg autoremove
# pkg clean
  11. To save disk space, clear any files cached by yarn, e.g. either 
    # rm -r /usr/local/share/.cache/yarn
    or 
    # rm -r /usr/local/share/.cache

Configuration

  1. Create a config_local.py as you would do for a Desktop installation of pgAdmin 4, e.g.: 
    # cat > web/config_local.py <<EOF
import os.path

DATA_DIR = "/var/db/pgadmin4"
LOG_FILE = os.path.join(DATA_DIR, 'pgadmin4.log')
SQLITE_PATH = os.path.join(DATA_DIR, 'pgadmin4.db')
TEST_SQLITE_PATH = os.path.join(DATA_DIR, 'test_pgadmin4.db')
SESSION_DB_PATH = os.path.join(DATA_DIR, 'sessions')
STORAGE_DIR = os.path.join(DATA_DIR, 'storage')
AZURE_CREDENTIAL_CACHE_DIR = os.path.join(DATA_DIR, 'azurecredentialcache')
KERBEROS_CCACHE_DIR = os.path.join(DATA_DIR, 'krbccache')

COOKIE_DEFAULT_PATH = "/pgadmin4/"
EOF
    This places everything in /var/db/pgadmin4. Have a look at web/config.py for a complete reference of all configuration knobs, e.g. if you want to disable the use of Gravatar images, configure a mail server for password resets, or authenticate users via OAuth/OIDC.
  2. Now create the data directory, and initialise the user database: 
    # mkdir /var/db/pgadmin4
# python web/setup.py setup-db
    You have to provide a valid email address, and a password with at least 6 characters.
  3. You can now leave the venv: 
    # deactivate
  4. While the Apache webserver will run as user www, pgAdmin will run with separate user privileges. Thus, you have to create this service account, and grant it write access to /var/db/pgadmin4: 
    # pw useradd pgadmin4 -c "pgAdmin 4 user" -d /usr/local/www/pgadmin4 -s /usr/sbin/nologin
# chown -R pgadmin4:pgadmin4 /var/db/pgadmin4/
  5. In /usr/local/etc/apache24/modules.d/270_mod_wsgi.conf, uncomment this line, which loads the wsgi module when Apache starts: 
    LoadModule wsgi_module        libexec/apache24/mod_wsgi.so
  6. Now, add the following either at the bottom of /usr/local/etc/apache24/httpd.conf, or place it inside a <VirtualHost> container: 
    WSGIDaemonProcess pgadmin4 processes=1 threads=25 user=pgadmin4 group=pgadmin4 python-home=/usr/local/www/pgadmin4
WSGIScriptAlias /pgadmin4 /usr/local/www/pgadmin4/pgadmin4-8.12/web/pgAdmin4.wsgi
<Directory /usr/local/www/pgadmin4/pgadmin4-8.12/web>
    WSGIProcessGroup pgadmin4
    AllowOverride None
    Options None
    Require all granted
</Directory>
    I experienced strange behaviour when using more than one process. Thus, I followed the official pgAdmin4 server deployment guide and increased the number of threads instead. The python-home option must point to the venv directory, of course. For a complete overview of all configuration options, please see the mod_wsgi documentation.
  7. Finally, let Apache start during system boot, and start it manually for now: 
    # sysrc apache24_enable=YES
# service apache24 start
  8. When examining the processlist, you will notice that one webserver process runs as user pgadmin4: 
    # ps axuww | grep httpd | grep -v grep
root     28353   0.0  0.2  27508  16752  -  Ss   23:09     0:00.31 /usr/local/sbin/httpd -DNOHTTPACCEPT
pgadmin4 28448   0.0  2.8 307008 230572  -  I    23:09     0:09.34 /usr/local/sbin/httpd -DNOHTTPACCEPT
www      29071   0.0  0.2  32144  20052  -  I    23:09     0:00.06 /usr/local/sbin/httpd -DNOHTTPACCEPT
www      29396   0.0  0.2  32144  20068  -  I    23:09     0:00.04 /usr/local/sbin/httpd -DNOHTTPACCEPT
www      29438   0.0  0.2  32144  20060  -  I    23:09     0:00.03 /usr/local/sbin/httpd -DNOHTTPACCEPT
www      30515   0.0  0.2  32144  20072  -  I    23:09     0:00.03 /usr/local/sbin/httpd -DNOHTTPACCEPT
www      31951   0.0  0.2  32144  20080  -  S    23:09     0:00.04 /usr/local/sbin/httpd -DNOHTTPACCEPT
www      32032   0.0  0.2  32144  20060  -  I    23:09     0:00.04 /usr/local/sbin/httpd -DNOHTTPACCEPT
www      32116   0.0  0.2  32144  20100  -  I    23:09     0:00.04 /usr/local/sbin/httpd -DNOHTTPACCEPT
www      47294   0.0  0.2  32144  20060  -  I    00:05     0:00.03 /usr/local/sbin/httpd -DNOHTTPACCEPT
www      47516   0.0  0.2  32144  20056  -  I    00:09     0:00.03 /usr/local/sbin/httpd -DNOHTTPACCEPT
www      50633   0.0  0.2  32144  19968  -  I    00:16     0:00.03 /usr/local/sbin/httpd -DNOHTTPACCEPT

Login