What you need
- An address for the CRM, usually a subdomain such as
crm.example.com, with an HTTPS certificate. Client Harbor only works over HTTPS. - An address for the client area (optional), such as
clients.example.com, where your clients sign in. - Python 3.12 or later on the server.
- A database: PostgreSQL 13 or later (recommended), or MySQL 8 / MariaDB 10.5 or later. On hosting, the installer uses PostgreSQL when the panel offers it, and MySQL or MariaDB otherwise.
| Where | How it's installed | Database | Background tasks |
|---|---|---|---|
| HostSecure hosting | One click, on HostSecure's Software page | PostgreSQL | A cron job |
| cPanel hosting | The installer file, in your browser | PostgreSQL if offered, else MySQL / MariaDB | A cron job |
| DirectAdmin | The installer file, in your browser | MySQL / MariaDB | A cron job |
| Plesk, CyberPanel and other panels | The installer file, with a database you make | PostgreSQL or MySQL / MariaDB | A cron job |
| Linux VPS or dedicated server | The install script, over SSH | PostgreSQL | Celery and Redis |
| Windows Server | By hand, with IIS | PostgreSQL | Task Scheduler |
Background tasks send task reminders, check mailboxes, raise recurring invoices and close old tickets. On hosting they run once a minute instead of continuously, which is all they need.
HostSecure hosting
HostSecure installs Client Harbor for you from its Software page. There's no file to upload, no API token to make and nothing for an administrator to switch on. It takes a few minutes.
- Make the address. In your HostSecure control panel, open Domains and add the CRM's address (for example
crm.example.com) as an add-on domain or a subdomain. Its HTTPS certificate is issued within a few minutes. - Open the installer. Open Software, then Websites, and under Business & Productivity click Install on Client Harbor.
- Fill in the form: the address, your license number (like
CH-7KQ2-M9XD-4TWA-HP3C; it comes with your order), your company name, your name and email (you'll sign in with them) and your time zone. - Click Install. HostSecure downloads Client Harbor, checks it, creates the database, installs it and puts it on the address. You can leave the page and come back; it shows the result when it's done.
- Copy the temporary password shown at the end. It's shown only once. Click Open Client Harbor, sign in, and change the password under your profile.
- Back up the encryption key. In File Manager, open
clientharbor/.envin your account's folder (besidepublic_html) and copyFIELD_ENCRYPTION_KEYsomewhere safe: stored email passwords can't be read without it.
The Client Harbor entry needs HostSecure 0.221 with patch 4 or later. On an older HostSecure, ask your host to update it, or use the installer file as on cPanel hosting; on HostSecure it asks for an API token and needs Running commands turned on for the account by an administrator.
On a HostSecure VPS or dedicated server where you want Client Harbor on its own, without HostSecure, follow Linux VPS or dedicated server instead.
What HostSecure sets up
- The app in a
clientharborfolder in your account's own folder, besidepublic_html, where no website serves it as files. Its settings are inclientharbor/.env. - A PostgreSQL database and user named after your account, such as
example_clientharbor, listed under Databases. - A cron job that runs the background tasks every minute.
- The address, over HTTP and HTTPS, switched to the app in HostSecure's App Manager, where you can restart it. The address's previous website stays in
public_htmland comes back if you remove the app.
After changing .env, restart the app from the App Manager. To remove Client Harbor, use Uninstall under Software → Websites → Installed apps: it removes the app, its database and its cron job. Back up first if you want to keep the data.
cPanel hosting
The installer works on any cPanel host that provides what Client Harbor needs (see the list after these steps). Its checks tell you whether your account qualifies before changing anything.
- Make the address. In cPanel, open Domains and click Create A New Domain. Enter the CRM's address (for example
crm.example.com) and leave the document root cPanel suggests. Its HTTPS certificate is issued within a few minutes; SSL/TLS Status shows when it's ready. - Download the installer. On the download page, click Download the installer. You get
clientharbor-install.php. Have your license number ready (likeCH-7KQ2-M9XD-4TWA-HP3C); it comes with your order. - Upload it. In cPanel's File Manager, open the folder of the address you made (for example
crm.example.com) and upload the installer there. Put it in that folder itself, not in a folder inside it. - Open it. Go to
https://crm.example.com/clientharbor-install.php. The installer checks the account first. If anything fails, it says what and changes nothing. - Fill in the form: your license number, your company name, your name and email (you'll sign in with them) and your time zone. To add the client area too, leave Also set up the client area ticked and check its address.
- Click Install Client Harbor and keep the page open. Each step is listed as it runs; installing the Python packages takes the longest. If a step fails, the page shows why, and Try again continues from that step.
- Save what it shows you. The last page shows your sign-in address, your email and a temporary password, and the encryption key. Keep the encryption key somewhere safe: stored email passwords can't be read without it. The installer then deletes itself.
If Client Harbor should replace a website already in that folder, the installer asks you to tick Replace the website first. It renames the site's index files to index.*.before-clientharbor and keeps a copy of its .htaccess, so nothing is deleted.
What the installer sets up on cPanel
- The app in
~/clientharbor, outside your website folders, with its settings in~/clientharbor/.env. - A database and user named after your account, such as
example_clientharbor: PostgreSQL if your cPanel offers it, else MySQL. The installer's checks show which before you start. - A cron job that runs the background tasks every minute.
- A few lines at the top of the website folder's
.htaccessthat send the address to the app.
After changing .env, restart the app by touching ~/clientharbor/tmp/restart.txt (in File Manager, open the file and save it).
What your cPanel host needs to provide
- Python 3.12 or later. On CloudLinux servers it's under Setup Python App in cPanel, and the installer finds it there.
- Passenger, which runs Python apps for the web server. cPanel's Application Manager and CloudLinux's Setup Python App both use it.
- PostgreSQL 13 or later (used when cPanel offers it), or MySQL 8 / MariaDB 10.5 or later.
- PHP that can run commands. Some hosts turn off
proc_open; the installer needs it.
If the installer says it needs a cPanel API token, open Security > Manage API Tokens in cPanel, create a token and paste it into the form. It's used only to create the database, cron job and subdomain; delete the token once Client Harbor is installed. If you'd rather not make a token, tick Use a database I've made myself and enter one you've created in cPanel instead.
If your host can't provide Python 3.12 or Passenger, ask them, or use a VPS.
DirectAdmin
The installer works on DirectAdmin too, on servers running CloudLinux or LiteSpeed (which provide Python 3.12 and Passenger); ask your host if you're not sure. Follow the cPanel steps, with these differences:
- Make the address under Subdomain Management (for example
crm), and under SSL Certificates get a free Let's Encrypt certificate that includes it. Upload the installer to the subdomain's folder,domains/example.com/public_html/crm. - The installer asks for a Login Key, so it can create the database, cron job and client area subdomain. In DirectAdmin, open Login Keys and create one that allows
CMD_API_SHOW_DOMAINS,CMD_API_SUBDOMAINS,CMD_API_DATABASESandCMD_API_CRON_JOBS. Delete it once Client Harbor is installed. Or tick Use a database I've made myself instead. - The database is MySQL or MariaDB, since that's what DirectAdmin offers. If your host added PostgreSQL to DirectAdmin, make a PostgreSQL database yourself and enter it in the form.
- For the client area, add its address to your Let's Encrypt certificate once the installer has made the subdomain.
Plesk, CyberPanel and other panels
On other hosting panels the installer can't create the database itself, so you make it first and enter it in the form. It does the rest the same way. The panel needs Python 3.12 or later and Passenger reading .htaccess files (CloudLinux and LiteSpeed servers have both), and PHP that can run commands.
- Make the address (for example
crm.example.com) with its own folder and an HTTPS certificate. - Make the database. Create a PostgreSQL database if your panel offers it, else a MySQL or MariaDB one, with a user that has all privileges on it. Note the database name, user name and password, with any prefix the panel adds.
- Upload and open the installer as in the cPanel steps, and enter the database in the form. The installer connects to it before installing anything, so a mistake shows up straight away.
- Finish what it lists. If the installer can't add the cron job or the client area subdomain itself, the last page shows what to add in your panel.
Installing by hand, over SSH
If PHP can't run commands on your hosting, install Client Harbor by hand instead. You need SSH access.
- Make the address and the database in your hosting panel, with an HTTPS certificate. For a MySQL or MariaDB database, set its collation to
utf8mb4_unicode_ci(in phpMyAdmin: Operations). - Upload the app. Download the release zip (
clientharbor-<version>.zip) from the download page and unpack it into aclientharborfolder in your home folder (not insidedomains), then make the folders it writes to:mkdir -p ~/clientharbor && cd ~/clientharbor && unzip ~/clientharbor-*.zip mkdir -p logs media private tmp - Install the Python packages. Use Python 3.12 or later (on CloudLinux it's in
/opt/alt):/opt/alt/python312/bin/python3 -m venv venv venv/bin/python -m pip install -r requirements/cpanel.txt - Make two keys. Run this twice, once for each key, and copy the results:
venv/bin/python -c "from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())" - Write the settings. Create
~/clientharbor/.envwith your values in place of the capitals and example addresses, and make it private withchmod 600 .env:
For MySQL or MariaDB, startDJANGO_SETTINGS_MODULE=config.settings.cpanel DEBUG=False SECRET_KEY=FIRST_KEY FIELD_ENCRYPTION_KEY=SECOND_KEY LICENSE_KEY=YOUR_LICENSE_NUMBER ALLOWED_HOSTS=crm.example.com SITE_URL=https://crm.example.com PORTAL_HOST=clients.example.com PORTAL_URL=https://clients.example.com DATABASE_URL=postgres://DB_USER:DB_PASSWORD@localhost/DB_NAME DEFAULT_FROM_EMAIL=noreply@example.com EMAIL_HOST=localhost EMAIL_PORT=25 EMAIL_USE_TLS=FalseDATABASE_URLwithmysql://instead. If the database password has characters other than letters and numbers, write them URL-encoded inDATABASE_URL(for example@as%40), or choose a password without them. Back upFIELD_ENCRYPTION_KEY: stored email passwords can't be read without it. - Create the tables and your administrator.
setup_instanceasks for your email, company, name, time zone and password:venv/bin/python manage.py migrate venv/bin/python manage.py collectstatic --no-input venv/bin/python manage.py setup_instance - Point the address at the app. Add these lines at the top of the
.htaccessfile in the subdomain's folder (on DirectAdmin,domains/example.com/public_html/crm), with your user name in place ofUSER:
Rename anyPassengerAppRoot "/home/USER/clientharbor" PassengerBaseURI "/" PassengerPython "/home/USER/clientharbor/venv/bin/python"index.htmlorindex.phpin that folder, since it would be shown instead. - Add the cron job. In your panel's cron jobs, add one that runs every minute (
*in every field):cd /home/USER/clientharbor && venv/bin/python manage.py run_scheduled >> logs/scheduled.log 2>&1 - For the client area, add its subdomain too, with its certificate, and give it the same
.htaccesslines.
Open https://crm.example.com and sign in. After changing .env, restart the app with touch ~/clientharbor/tmp/restart.txt.
Linux VPS or dedicated server
On a blank server of your own, Client Harbor runs with PostgreSQL, nginx, and Celery and Redis for the background tasks. One install script sets all of it up, with the HTTPS certificate, on:
- Ubuntu 24.04 LTS
- AlmaLinux 9 (9.4 or later). Rocky Linux 9 and RHEL 9 use the same steps.
Use a fresh server with nothing else on it: the script takes over the web server (ports 80 and 443). A small VPS is enough: 2 GB of memory, 1 or 2 CPUs and 20 GB of disk.
- Point the addresses at the server. Add a DNS
Arecord forcrm.example.com, and one forclients.example.comif you'll use the client area, with the server's IP address. Wait until they resolve; the HTTPS certificate needs them. - Sign in over SSH as root, or as a user that can use
sudo. - Run the installer with your address, your license number and the email Let's Encrypt should send certificate notices to. Add
PORTAL_HOST=clients.example.comif you'll use the client area:
It installs what it needs to download Client Harbor, downloads the newest release and refuses it unless its checksum matches. Then it installs the system packages, puts the app incurl -fsSL https://clientharbor.org/releases/install.sh | sudo DOMAIN=crm.example.com LICENSE_KEY=YOUR_LICENSE_NUMBER CERTBOT_EMAIL=you@example.com bash/var/www/clientharbor, creates the database, writes.envwith new keys, gets the HTTPS certificate and starts the services. It opens ports 80 and 443 in the firewall if one is running, and on AlmaLinux it sets SELinux up for nginx. It takes 5 to 10 minutes and is safe to run again: it keeps your keys and data, and takes any new address or license number you give it.To install from a release you downloaded yourself, unzip it and run
sudo DOMAIN=crm.example.com LICENSE_KEY=YOUR_LICENSE_NUMBER CERTBOT_EMAIL=you@example.com bash deploy/install.shfrom its folder. - Create your administrator. It asks for your email, company, name, time zone and password:
cd /var/www/clientharbor && sudo -u clientharbor venv/bin/python manage.py setup_instance - Back up the encryption key. Copy
FIELD_ENCRYPTION_KEYfrom/var/www/clientharbor/.envsomewhere safe: stored email passwords can't be read without it.
Open https://crm.example.com and sign in. The app runs as its own clientharbor user, which can write only to its uploads and logs. After changing .env, restart with:
sudo systemctl restart clientharbor clientharbor-celery clientharbor-celerybeat
Updating
To update to the newest release, run this on the server:
curl -fsSL https://clientharbor.org/releases/update.sh | sudo bash
It checks for a new release, downloads it and checks its checksum, backs up the database and the app to /var/backups/clientharbor (the last three are kept), then updates and restarts Client Harbor. Your addresses, license number, keys, uploads and HTTPS certificate are kept, so there's nothing to type. If any step fails, it puts the backup back and starts the old version again. It never installs an older release over a newer one. What changed is on the Changelog page, under Documentation.
Run the install script again only to change the addresses or add the license number.
Other Linux distributions
The script refuses other systems. On Debian and others, set up the same pieces by hand, following deploy/install.sh:
- Install Python 3.12 or later, PostgreSQL, Redis and nginx, and get a certificate (for example with certbot).
- Create a PostgreSQL user and database, put the app in
/var/www/clientharbor, make a virtualenv there and runvenv/bin/pip install -r requirements/prod.txt. - Copy
.env.exampleto.envand fill it in, withDJANGO_SETTINGS_MODULE=config.settings.prodand your license number inLICENSE_KEY, then runmigrate,collectstatic --no-inputandsetup_instance. - Install the three services in
deploy/(clientharbor.service,clientharbor-celery.serviceandclientharbor-celerybeat.service) with systemd, and adaptdeploy/nginx.confto your addresses and certificate.
Windows Server
On Windows Server 2019 or later, IIS takes the web requests and starts Client Harbor with Waitress. The background tasks run from Task Scheduler every minute, so Redis isn't needed. The steps use C:\ClientHarbor; run the commands in PowerShell as an administrator.
- Install what it needs:
- Python 3.12 or later from python.org. Choose Customize installation and Install Python for all users, so IIS can use it.
- PostgreSQL from postgresql.org. Remember the password you give the
postgresuser. - IIS: in Server Manager, add the Web Server (IIS) role.
- HttpPlatformHandler, Microsoft's IIS module for running apps like this one, from iis.net.
- Make the database. In pgAdmin (installed with PostgreSQL), or with
psql -U postgres, run this with a password of your own:CREATE USER clientharbor WITH PASSWORD 'a long random password'; CREATE DATABASE clientharbor OWNER clientharbor; - Unpack the app. Download the release zip from the download page, unpack it into
C:\ClientHarbor, and install the packages:cd C:\ClientHarbor mkdir logs, media, private, site py -3 -m venv venv venv\Scripts\python -m pip install -r requirements\windows.txt - Make two keys. Run this twice, once for each key:
venv\Scripts\python -c "from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())" - Write the settings. In Notepad, create
C:\ClientHarbor\.envwith your values in place of the capitals and example addresses (choose All files when saving, so it isn't saved as.env.txt):
As on DirectAdmin, URL-encode any characters other than letters and numbers in the database password. Back upDJANGO_SETTINGS_MODULE=config.settings.windows DEBUG=False SECRET_KEY=FIRST_KEY FIELD_ENCRYPTION_KEY=SECOND_KEY LICENSE_KEY=YOUR_LICENSE_NUMBER ALLOWED_HOSTS=crm.example.com SITE_URL=https://crm.example.com PORTAL_HOST=clients.example.com PORTAL_URL=https://clients.example.com DATABASE_URL=postgres://clientharbor:DB_PASSWORD@localhost:5432/clientharbor DEFAULT_FROM_EMAIL=noreply@example.comFIELD_ENCRYPTION_KEY. - Create the tables and your administrator:
venv\Scripts\python manage.py migrate venv\Scripts\python manage.py collectstatic --no-input venv\Scripts\python manage.py setup_instance - Add the IIS site. Save this as
C:\ClientHarbor\site\web.config:
In IIS Manager, add an application pool named<?xml version="1.0" encoding="utf-8"?> <configuration> <system.webServer> <handlers> <add name="httpPlatformHandler" path="*" verb="*" modules="httpPlatformHandler" resourceType="Unspecified" /> </handlers> <httpPlatform processPath="C:\ClientHarbor\venv\Scripts\python.exe" arguments="-m waitress --listen=127.0.0.1:%HTTP_PLATFORM_PORT% --url-scheme=https config.wsgi:application" stdoutLogEnabled="true" stdoutLogFile="C:\ClientHarbor\logs\waitress.log" startupTimeLimit="60"> <environmentVariables> <environmentVariable name="PYTHONPATH" value="C:\ClientHarbor" /> <environmentVariable name="DJANGO_SETTINGS_MODULE" value="config.settings.windows" /> </environmentVariables> </httpPlatform> <security><requestFiltering><requestLimits maxAllowedContentLength="26214400" /></requestFiltering></security> </system.webServer> </configuration>Client Harborwith No Managed Code, then a website that uses it, withC:\ClientHarbor\siteas its physical path. Give the app pool access to the app's folder:icacls C:\ClientHarbor /grant "IIS AppPool\Client Harbor:(OI)(CI)M" - Add HTTPS. Get a certificate for the CRM's address (and the client area's), for example with the free win-acme tool for Let's Encrypt, and bind it to the site on port 443. Bind the site to HTTPS only: Client Harbor treats every request as secure, so sign-in doesn't work over plain HTTP. To send
http://visitors to HTTPS, add a separate site on port 80 that redirects. - Schedule the background tasks:
schtasks /Create /TN "Client Harbor scheduled tasks" /SC MINUTE /MO 1 /RU SYSTEM /TR "cmd /c C:\ClientHarbor\venv\Scripts\python.exe C:\ClientHarbor\manage.py run_scheduled >> C:\ClientHarbor\logs\scheduled.log 2>&1"
Open https://crm.example.com and sign in. After changing .env, recycle the Client Harbor application pool in IIS Manager.
Updating Client Harbor
On hosting (HostSecure, cPanel, DirectAdmin and other panels), Client Harbor updates itself. Open Setup, then Updates: it shows the installed version and the newest one. Click Update to the new version, and within a minute the every-minute cron job starts the update. The page shows how it's going, and Client Harbor may stop answering for a moment while it restarts.
- The database and the app are backed up first, into the
backupsfolder of the install (the last three are kept). - Your settings (
.env), uploaded files and imports are kept. - If any step fails, the old version and the database are put back, and Updates says what went wrong.
- The backup needs
pg_dump(PostgreSQL) ormysqldump(MySQL and MariaDB) on the server, which hosting servers usually have. Without it, the update stops before changing anything and says so.
With SSH access, you can also update from the command line: cd ~/clientharbor && venv/bin/python manage.py update (--check only says whether there's a new version).
On a server installed with the install script, update as root: see Updating in the Linux section.
After installing
- Sign in with the email and password from the installer or
setup_instance, and change a temporary password under your profile. - Keep the encryption key safe, away from the server. Back up the database and the
mediafolder (uploaded files) too. - Continue with the How to Set up Client Harbor Step by Step guide in the app's Documentation, starting with outgoing email, so invitations and password resets can be sent.