This will be done on in a clean environment, but so long as you are running a modern version of FreeBSD (13.1 as of this writing), you should have no trouble.
- Testing on FreeBSD 13.1
- Tested with Python 3.9
- Internet Access
All these commands unless otherwise noted where executed as the root user.
Install Required Software
All the prerequisite software and libraries are available in the FreeBSD ports system. The process is not difficult, but requires several unique steps that would normally be handled by an installation script or package. Fortunately for us, FreeBSD makes it all extremely easy.
Use the FreeBSD package to install Python's virtual environment tooling. No need for Pipenv, we'll use the system's Python.
pkg install py39-virtualenv
For our installation we are using Python 3.9. Replace the version number above if you are using a later version.
Since we are using virtual environment, none of the system Python libraries will be visible to PgAdmin. There are a few libraries that will need to be built from source. In order for that to be successful you'll need some header files and a Rust compiler.
pkg install jpeg-turbo postgresql13-client py39-sqlite3 rust
Replace the version of PostgreSQL and Python with the ones you are using.
Apache with mod_wsgi
Install and enable Apache and the wsgi module. Substitute the python and Apache versions accordingly.
pkg install apache24 ap24-py39-mod_wsgi
service apache24 enable
sed -i '' 's,#\(LoadModule wsgi_module.*$\),\1,g' /usr/local/etc/apache24/modules.d/270_mod_wsgi.conf
Install PgAdmin 4
Create the home, log, data directories, and a configuration file that will be used by PgAdmin and set the correct ownership and permissions.
install -d -o www -g www /usr/local/www/pgadmin4 /var/log/pgadmin4 /var/db/pgadmin4 /var/db/pgadmin4/sessions
install -d -o root -g www -m 750 /usr/local/etc/pgadmin4
Create and link to the configuration file named config_local.py.
cat << EOF >/usr/local/etc/pgadmin4/config_local.py
LOG_FILE = '/var/log/pgadmin4/pgadmin4.log'
SQLITE_PATH = '/var/db/pgadmin4/pgadmin4.db'
SESSION_DB_PATH = '/var/db/pgadmin4/sessions'
STORAGE_DIR = '/var/db/pgadmin4/storage'
AZURE_CREDENTIAL_CACHE_DIR = '/var/db/pgadmin4/azurecredentialcache'
KERBEROS_CCACHE_DIR = '/var/db/pgadmin4/kerberoscache'
Since this will be running as the same user as Apache, switch to the www user and set the home directory environmental variable.
su -m www -c /bin/sh
Create a new virtual environment for PgAdmin in your web server's file store.
Activate the virtual environment.
If using FreeBSD's csh, use the corresponding activation script.
Use pip install to automatically download and install PgAdmin 4 and all the dependencies. This could take a while
pip install pgadmin4
Link to the configuration created earlier config_local.py.
ln -s /usr/local/etc/pgadmin4/config_local.py /usr/local/www/pgadmin4/lib/python3.9/site-packages/pgadmin4/config_local.py
Create a link for "web" sub-directory to point to the application
ln -s /usr/local/www/pgadmin4/lib/python3.9/site-packages/pgadmin4 web
Run the following command to create the configuration database.
When prompted enter an email address and password to be used for logging into the application.
NOTE: Configuring authentication for SERVER mode.
Enter the email address and password to use for the initial pgAdmin user account:
Email address: email@example.com
pgAdmin 4 - Application Initialisation
You may exit and return to being root.
We won't go into the details on how to get Apache properly setup. The remainder of this article assumes you already have a functional Virtual Hosting environment running. We'll create a new Apache VHost just for the purpose of running PgAdmin 4. The remaining steps should be executed as root
Before it will work, we need to make a minor tweak (as per official documentation) to the wsgi startup script.
Add the following line to the top of the file to activate the virtual environment when Apache serves the application. It's perfectly fine to put it all the way at the top before the comments or directly after the comments. The only requirement is that it must run before any other Python code gets executed.
activate_this = '/usr/local/www/pgadmin4/bin/activate_this.py'
I have a hostname "pgadmin" setup that points to my server's IP address. Consult your DNS server documentation on how to create a hostname.
# host pgadmin
pgadmin.myserver.dev is an alias for server.myserver.dev.
server.myserver.dev has address 192.168.1.254
I keep the directives for each site in individual files and have Apache load them from a directory called "Sites". If you wish to do the same create a file in the Apache Includes directory that contains a directive to load conf files from a Sites directory as shown below.
cat << EOF >/usr/local/etc/apache24/Includes/sites.conf
Create a new vhost in Apache using the one site per config layout. Create a file in the Sites directory. Replace the ServerName and ServerAlias directives as needed.
cat << EOF >/usr/local/etc/apache24/Sites/pgadmin4.conf
WSGIDaemonProcess pgadmin processes=1 threads=25 python-home=/usr/local/www/pgadmin4
WSGIScriptAlias / /usr/local/www/pgadmin4/web/pgAdmin4.wsgi
Require all granted
Now start up Apache.
service apache24 start
Open your browser and navigate to the hostname you setup for the vHost. Log in with the username and password you setup earlier.