Install guide

Installing Client Harbor

Client Harbor runs on your own server or hosting account. On shared hosting (HostSecure, cPanel, DirectAdmin and most other panels), a single installer file does it for you. On other servers, follow the steps for yours below. Once it's installed, continue with the How to Set up Client Harbor Step by Step guide in the app's Documentation.

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.
WhereHow it's installedDatabaseBackground tasks
HostSecure hostingOne click, on HostSecure's Software pagePostgreSQLA cron job
cPanel hostingThe installer file, in your browserPostgreSQL if offered, else MySQL / MariaDBA cron job
DirectAdminThe installer file, in your browserMySQL / MariaDBA cron job
Plesk, CyberPanel and other panelsThe installer file, with a database you makePostgreSQL or MySQL / MariaDBA cron job
Linux VPS or dedicated serverThe install script, over SSHPostgreSQLCelery and Redis
Windows ServerBy hand, with IISPostgreSQLTask 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.

  1. 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.
  2. Open the installer. Open Software, then Websites, and under Business & Productivity click Install on Client Harbor.
  3. 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.
  4. 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.
  5. 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.
  6. Back up the encryption key. In File Manager, open clientharbor/.env in your account's folder (beside public_html) and copy FIELD_ENCRYPTION_KEY somewhere 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 clientharbor folder in your account's own folder, beside public_html, where no website serves it as files. Its settings are in clientharbor/.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_html and 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.

  1. 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.
  2. Download the installer. On the download page, click Download the installer. You get clientharbor-install.php. Have your license number ready (like CH-7KQ2-M9XD-4TWA-HP3C); it comes with your order.
  3. 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.
  4. 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.
  5. 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.
  6. 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.
  7. 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 .htaccess that 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_DATABASES and CMD_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.

  1. Make the address (for example crm.example.com) with its own folder and an HTTPS certificate.
  2. 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.
  3. 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.
  4. 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.

  1. 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).
  2. Upload the app. Download the release zip (clientharbor-<version>.zip) from the download page and unpack it into a clientharbor folder in your home folder (not inside domains), then make the folders it writes to:
    mkdir -p ~/clientharbor && cd ~/clientharbor && unzip ~/clientharbor-*.zip
    mkdir -p logs media private tmp
  3. 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
  4. 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())"
  5. Write the settings. Create ~/clientharbor/.env with your values in place of the capitals and example addresses, and make it private with chmod 600 .env:
    DJANGO_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=False
    For MySQL or MariaDB, start DATABASE_URL with mysql:// instead. If the database password has characters other than letters and numbers, write them URL-encoded in DATABASE_URL (for example @ as %40), or choose a password without them. Back up FIELD_ENCRYPTION_KEY: stored email passwords can't be read without it.
  6. Create the tables and your administrator. setup_instance asks 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
  7. Point the address at the app. Add these lines at the top of the .htaccess file in the subdomain's folder (on DirectAdmin, domains/example.com/public_html/crm), with your user name in place of USER:
    PassengerAppRoot "/home/USER/clientharbor"
    PassengerBaseURI "/"
    PassengerPython "/home/USER/clientharbor/venv/bin/python"
    Rename any index.html or index.php in that folder, since it would be shown instead.
  8. 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
  9. For the client area, add its subdomain too, with its certificate, and give it the same .htaccess lines.

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.

  1. Point the addresses at the server. Add a DNS A record for crm.example.com, and one for clients.example.com if you'll use the client area, with the server's IP address. Wait until they resolve; the HTTPS certificate needs them.
  2. Sign in over SSH as root, or as a user that can use sudo.
  3. 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.com if you'll use the client area:
    curl -fsSL https://clientharbor.org/releases/install.sh | sudo DOMAIN=crm.example.com LICENSE_KEY=YOUR_LICENSE_NUMBER CERTBOT_EMAIL=you@example.com bash
    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 in /var/www/clientharbor, creates the database, writes .env with 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.sh from its folder.

  4. 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
  5. Back up the encryption key. Copy FIELD_ENCRYPTION_KEY from /var/www/clientharbor/.env somewhere 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:

  1. Install Python 3.12 or later, PostgreSQL, Redis and nginx, and get a certificate (for example with certbot).
  2. Create a PostgreSQL user and database, put the app in /var/www/clientharbor, make a virtualenv there and run venv/bin/pip install -r requirements/prod.txt.
  3. Copy .env.example to .env and fill it in, with DJANGO_SETTINGS_MODULE=config.settings.prod and your license number in LICENSE_KEY, then run migrate, collectstatic --no-input and setup_instance.
  4. Install the three services in deploy/ (clientharbor.service, clientharbor-celery.service and clientharbor-celerybeat.service) with systemd, and adapt deploy/nginx.conf to 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.

  1. 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 postgres user.
    • IIS: in Server Manager, add the Web Server (IIS) role.
    • HttpPlatformHandler, Microsoft's IIS module for running apps like this one, from iis.net.
  2. 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;
  3. 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
  4. Make two keys. Run this twice, once for each key:
    venv\Scripts\python -c "from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())"
  5. Write the settings. In Notepad, create C:\ClientHarbor\.env with your values in place of the capitals and example addresses (choose All files when saving, so it isn't saved as .env.txt):
    DJANGO_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.com
    As on DirectAdmin, URL-encode any characters other than letters and numbers in the database password. Back up FIELD_ENCRYPTION_KEY.
  6. 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
  7. Add the IIS site. Save this as C:\ClientHarbor\site\web.config:
    <?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>
    In IIS Manager, add an application pool named Client Harbor with No Managed Code, then a website that uses it, with C:\ClientHarbor\site as its physical path. Give the app pool access to the app's folder:
    icacls C:\ClientHarbor /grant "IIS AppPool\Client Harbor:(OI)(CI)M"
  8. 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.
  9. 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 backups folder 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) or mysqldump (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 media folder (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.