Troubleshooting
Most problems show a message in Harblet that says what to do. This page covers the cases where you need the server's command line. Run the commands on the first server.
The install script stops
| Message | What to do |
|---|---|
| k3s is already installed on this server, so Harblet can't be installed. | Use a fresh server, or remove k3s with sudo /usr/local/bin/k3s-uninstall.sh first. This deletes everything k3s ran. |
| This server's IPv4 address couldn't be found. | Set HARBLET_URL, see Servers behind NAT. |
| k3s didn't become ready within 5 minutes. | Check that the server meets the requirements, then start over. |
| Installing Harblet failed. To start over, run /usr/local/bin/k3s-uninstall.sh and then this script again. | Run sudo /usr/local/bin/k3s-uninstall.sh, fix the cause shown above the message, and run the install command again. |
Logins are rejected
Harblet accepts logins only at its own address: the one the install script printed, or https://<domain> once Harblet has its own domain. Open Harblet at exactly that address.
If your browser can't reach that address, for example because the server is behind NAT, set the address Harblet runs at:
sudo k3s kubectl -n harblet-system set env deployment/harblet -c harblet NUXT_PUBLIC_SITE_URL=http://203.0.113.10:3000
Harblet restarts with the new address within seconds.
Harblet isn't reachable at its domain
If you saved a wrong domain under Settings → General, or its DNS or certificate doesn't work, either fix the DNS record, or move Harblet back to its IP address with the command above. Then log in at http://<ip>:3000 and set the domain again.
Port 3000 has to be open for this. If you closed it in your firewall, open it again first.
An update doesn't start
If a new version of Harblet doesn't come up after an update, switch back to the version you had before:
sudo k3s kubectl -n harblet-system set image deployment/harblet harblet=ghcr.io/harblet/harblet:<old version>
A k3s upgrade is stuck
The Servers page shows The k3s upgrade is stuck with Kubernetes' message, or a server shows Upgrading to for a long time.
- If the message says an image can't be pulled, check that the server can reach the internet. Kubernetes keeps trying by itself.
- If you went back to an older Harblet that shouldn't upgrade k3s anymore, stop the upgrade:
sudo k3s kubectl -n harblet-system delete plans --all
Services don't start after a reboot
Image services and databases ask their registry for their image every time they start, for example Docker Hub. If the registry can't be reached right after a reboot, they stay down until it can. They start by themselves once the server is online again. Services built from Git start from the image on the server.
The first build fails right after the install or a reboot
Right after k3s starts, the cluster's DNS may not answer yet, and the clone step of a build fails. Click Deploy again a minute later.
A removed server doesn't boot completely
A server you removed keeps trying to reconnect until you uninstall the k3s agent on it. Log in over SSH and run:
sudo /usr/local/bin/k3s-agent-uninstall.sh
Someone forgot their password
Harblet has no password reset yet. An admin removes the member under Members and invites them again. Their deployments stay.
Get help
Look for an existing issue or open a new one on GitHub, or write to mail@harblet.com.