Harbor documentation

Features, mapped to cPanel

Install

On a fresh Ubuntu 24.04 / 22.04 or Debian 12 VPS:

tar xzf harbor.tar.gz && cd harbor
sudo ./install.sh --hostname server1.example.com --email you@example.com

Open https://SERVER-IP:8443 (self-signed certificate warning the first time) and sign in with the printed password. Then in Settings: confirm the host name and IP, set your name servers, and click Get certificate to give the panel, webmail and mail server a trusted certificate.

Options: --admin NAME, --port N, --extra-php "8.2 8.1" (adds the Ondřej Surý PHP repository), --no-mail, --no-dns, --no-modsec, --no-webmail. Re-running the installer upgrades Harbor in place and keeps all data.

Before you rely on email

• Ask your VPS provider to open outbound port 25 (many block it) and to set reverse DNS (PTR) for the server IP to your host name.
• The host name needs an A record pointing at the server.
• If DNS for a domain is hosted elsewhere, add the MX/SPF/DKIM/DMARC records shown on its Email tab.

Hosting DNS here

Create "glue" records ns1.yourdomain.com / ns2.yourdomain.com → server IP at your registrar, set them in Settings, and use them as each domain's name servers. BIND runs authoritative-only (no open resolver). For real redundancy, add a secondary DNS provider later.

After installing: secure the server

1. My account → Two-factor sign-in. Scan the QR code and save the recovery codes.
2. Security → Two-factor sign-in → Require for all admins.
3. Security → Panel access. Add your own IP address(es). Locked out later? sudo /opt/harbor/venv/bin/python -m harbor allow-ip --clear
4. Settings → Offsite backups. Connect a private bucket, then turn on daily backups per site (Backups tab).
5. Settings → Alerts. Add your email and an SMTP server (outgoing port 25 is often blocked), or a Slack/Discord webhook, and click Send test alert.
6. Settings → General → Default limits, and per site on its Overview tab.

Each site's PHP now runs as its own service, harbor-php-<site> (systemctl status harbor-php-site1), so limits are enforced by the kernel and one site can't starve the others. Upgrading from 0.2 moves existing sites over automatically.

Deploying from Git

Each site has a Deploy tab.

1. Connect the repository address and branch. Public repositories work with their https:// address; for a private one use the SSH address (git@github.com:owner/repo.git) and add the deploy key Harbor shows as a read-only key in the repository (GitHub: Settings → Deploy keys). Check connection confirms it.
2. Optional: a build command (composer install --no-dev, npm ci && npm run build) that runs in the repository as the site's own user, a folder to publish (e.g. dist), an after-deploy command that runs in the live folder (php artisan migrate --force), and paths to keep on the live site (wp-content/uploads/, .env).
3. Deploy now. Harbor fetches the branch, builds, then copies the result into the site with rsync. If the fetch or build fails, the live site isn't touched. The first deploy backs up the current files and databases first.
4. Deploy on push: add the webhook address shown on the tab to the repository (JSON, push events). Pushes to other branches are ignored; GitHub/Gitea signatures and GitLab tokens are checked when sent. The webhook path /hooks/ stays reachable when the panel is limited to your IP addresses.
5. Roll back with Redeploy this version on any earlier deploy. From CI: curl -X POST -H "Authorization: Bearer hbr_…" https://server:8443/api/v1/sites/ID/deploy.

The working copy lives in /srv/harbor/sites/<domain>/git/ (outside the web root). Disconnecting deletes it and the key; the live files stay.

Moving from cPanel

1. On the old host: cPanel → Backup → Download a Full Account Backup (destination: Home Directory). On WHM, a cpmove-USER.tar.gz from the Transfer Tool or pkgacct works too.
2. Harbor → Move from cPanel: drop the file on the page, paste a download link, or copy it to /srv/harbor/imports/ with scp (best for many-GB backups) and click Use this.
3. Review the plan (domains, databases, mailboxes, DNS, cron), untick what you don't want, Import now.
4. Follow the Next steps on the result page: preview with a hosts-file line, point DNS, turn on HTTPS, move MX last. The Health page then tells you what still points at the old host.

What carries over: main, addon, sub and parked domains (parked ones redirect to the main domain); files with /home/USER paths rewritten in configs; databases and their users with the same passwords (MySQL 8 caching_sha2 users get a new password, written into WordPress/Joomla/Laravel settings); mailboxes with their original passwords, quotas, every folder and read/unread state; forwarders, catch-all, autoresponders; DNS zones without cPanel-only records and with the old IP replaced; cron jobs with new paths and PHP. Not carried over: SSL certificates (re-issued free), FTP accounts (use SFTP), mail filters, statistics, and .htaccess rules (nginx doesn't read them: the summary lists sites with custom rules to recreate under Redirects/Security). The old account is never touched.

Updating

Harbor checks for a new release every 6 hours. When one is out, the dashboard shows a banner with Update now, Settings gets an "Update" badge, and admins are told by email or webhook (whatever is set under Settings → Alerts), once per release. Settings → Updates shows the release notes and has Check now and the update settings (turn checking or notifications off).

Updating saves the current code and database, installs, restarts and checks that the panel answers. If anything fails it puts the previous version back by itself. When a release also changes server components, the installer runs automatically as part of the update (it keeps data and settings).

You can also upload a harbor.tar.gz (or paste a link) on the same page, or from SSH: sudo /opt/harbor/venv/bin/python -m harbor update harbor.tar.gz.

Servers installed before 0.7.0 don't have update checks yet: update once by hand: in the folder you cloned Harbor into, run git pull && sudo ./install.sh (or upload the 0.7.0 package on Settings → Updates).

Ports

API

Create a token under your account (top-left user name → API tokens):

curl -H "Authorization: Bearer hbr_…" https://server:8443/api/v1/sites
curl -X POST -H "Authorization: Bearer hbr_…" -H "Content-Type: application/json" \
     -d '{"domain":"example.com"}' https://server:8443/api/v1/sites

Endpoints: sites (list/create/show/HTTPS), databases, backups, mailboxes, DNS records, Git deploys (POST /api/v1/sites/ID/deploy, GET /api/v1/sites/ID/deployments). The account page lists them all.

Security model

• Every site runs PHP as its own Linux user with open_basedir; one compromised site can't read another's files. SFTP users are chrooted and have no shell.
• The panel listens on 127.0.0.1:8090 behind nginx TLS. Sessions are signed, Secure, HttpOnly, SameSite=Strict; all forms have CSRF tokens; logins are throttled; strict CSP.
• System commands run as argument lists (never through a shell). Every value written to a config file goes through strict validation, so input can't inject directives.
• Every nginx, PHP-FPM, BIND and Postfix change is checked (nginx -t, php-fpm -t, named-checkzone, postmap) and rolled back if rejected.
• Mail: no open relay; authenticated senders can only send as their own address; DKIM on all outgoing mail.
• The panel itself runs as root (it creates users and manages services). If you can, allow port 8443 only from your own IPs: ufw allow from 203.0.113.4 to any port 8443.

Files on the server

Operate: systemctl status harbor, journalctl -u harbor -f.

Command line (cd /opt/harbor && sudo venv/bin/python -m harbor …):

Development

pip install -r requirements.txt pytest httpx moto
python -m pytest -q tests                      # dry-run tests: no system changes
HARBOR_DRY_RUN=1 python -m harbor create-admin admin --password 'long-password-here'
HARBOR_DRY_RUN=1 HARBOR_COOKIE_SECURE=0 python -m harbor serve --port 8090

Dry-run mode sandboxes every path and logs commands instead of running them. tests/integration/run_live.py (73 checks: web, PHP isolation, DNS, mail delivery/DKIM/relay protection, autoresponders, SFTP chroot, ModSecurity, backups/restore, team users, API) and tests/integration/run_stage1.py (38 checks: per-site PHP services and limits, migration from 0.2, 2FA, fail2ban bans, panel allowlist, offsite backup and restore, alerts, update and rollback) and tests/integration/run_stage2.py (46 checks: importing a realistic cPanel account in both backup layouts, then checking sites, original database and mailbox passwords, old mail and folders, forwarders, catch-all, autoresponder, DNS, cron, health pages) and tests/integration/run_deploy.py (32 checks: Git deploy from a private SSH repository with a deploy key, build as the site user, kept paths, push webhook through nginx past the panel allowlist, failed build leaves the site alone, rollback, disconnect) exercise a real server end to end.

Not included yet

• Staging sites, Node.js/Python apps
• DNSSEC signing and secondary DNS; reseller packages
• Disk limits are soft (alerts + upload block), not filesystem quotas; cron jobs aren't covered by CPU/memory limits

This page is generated from the Harbor app's README.md.