Client Harbor
Install guide

Installing Client Harbor

Client Harbor runs on your own server or hosting account. On cPanel hosting, a single installer file does everything 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 on your own server), or MySQL 8 / MariaDB 10.5 or later (what cPanel and DirectAdmin hosting provide).
WhereHow it's installedDatabaseBackground tasks
HostSecure and other cPanel hostingThe installer file, in your browserMySQL / MariaDBA cron job
DirectAdminBy hand, over SSHMySQL / 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 hosting accounts already have everything Client Harbor needs, so the installer does all the work. It takes about ten minutes.

  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.

On a HostSecure VPS or dedicated server, follow Linux VPS or dedicated server instead.

What the installer sets up

  • The app in ~/clientharbor, outside your website folders, with its settings in ~/clientharbor/.env.
  • A MySQL database and user named after your account, such as example_clientharbor.
  • 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).

Other cPanel hosting

The installer works on any cPanel host that provides what Client Harbor needs. Follow the HostSecure steps; the installer's checks tell you whether your account qualifies before changing anything. It needs:

  • 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.
  • MySQL 8 or 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 your host can't provide Python 3.12 or Passenger, ask them, or use a VPS.

DirectAdmin

The installer only works with cPanel, so on DirectAdmin Client Harbor is installed by hand. You need SSH access, and a server running CloudLinux (which provides Python 3.12 and Passenger); ask your host if you're not sure.

  1. Make the address. In DirectAdmin, add the subdomain (for example crm) under Subdomain Management. Under SSL Certificates, get a free Let's Encrypt certificate that includes it, and turn on Force SSL.
  2. Make the database. Under MySQL Management, create a database and user and note the database name, user name and password. Then in phpMyAdmin, select the database, open Operations and set its collation to utf8mb4_unicode_ci.
  3. 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
  4. 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
  5. 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())"
  6. 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=mysql://DB_USER:DB_PASSWORD@localhost/DB_NAME
DEFAULT_FROM_EMAIL=noreply@example.com
EMAIL_HOST=localhost
EMAIL_PORT=25
EMAIL_USE_TLS=False
    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.
  7. 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
  8. Point the address at the app. Add these lines at the top of the .htaccess file in the subdomain's folder (DirectAdmin makes it at 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.
  9. Add the cron job. Under 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
  10. 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 server of your own, Client Harbor runs with PostgreSQL, nginx, and Celery and Redis for the background tasks. The install script sets all of it up on Ubuntu 24.04 LTS. Use a fresh server, since it takes over nginx's default site.

  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. Copy the app to the server. Sign in over SSH as root (or a user that can use sudo). Download the release zip from the download page and unpack it: 
    apt-get install -y unzip
mkdir clientharbor && cd clientharbor && unzip ../clientharbor-*.zip
  3. Run the install script with your addresses, and the email Let's Encrypt should send certificate notices to. Leave out PORTAL_HOST if you won't use the client area: 
    sudo DOMAIN=crm.example.com PORTAL_HOST=clients.example.com LICENSE_KEY=YOUR_LICENSE_NUMBER CERTBOT_EMAIL=you@example.com bash deploy/install.sh
    It installs the system packages, puts the app in /var/www/hostsecurecrm, creates the database, writes .env with new keys, starts the services and gets the HTTPS certificate. It's safe to run again; it keeps your settings and data.
  4. Create your administrator. It asks for your email, company, name, time zone and password: 
    cd /var/www/hostsecurecrm && sudo -u www-data venv/bin/python manage.py setup_instance
  5. Back up the encryption key. Copy FIELD_ENCRYPTION_KEY from /var/www/hostsecurecrm/.env somewhere safe: stored email passwords can't be read without it.

After changing .env, restart with:

sudo systemctl restart hostsecurecrm hostsecurecrm-celery hostsecurecrm-celerybeat

Other Linux distributions

On Debian, AlmaLinux, Rocky Linux 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/hostsecurecrm, 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/ (hostsecurecrm.service, celery.service and 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:\Client Harbor; 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:\Client Harbor, and install the packages: 
    cd C:\Client Harbor
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:\Client Harbor\.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:\Client Harbor\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:\Client Harbor\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:\Client Harbor\logs\waitress.log" startupTimeLimit="60">
      <environmentVariables>
        <environmentVariable name="PYTHONPATH" value="C:\Client Harbor" />
        <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:\Client Harbor\site as its physical path. Give the app pool access to the app's folder: 
    icacls C:\Client Harbor /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:\Client Harbor\venv\Scripts\python.exe C:\Client Harbor\manage.py run_scheduled >> C:\Client Harbor\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.

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.