Error finder: look up self-hosting error messages
Container won't start, certificate missing, mail stuck? Search your error message – every answer comes from a setup we got running ourselves.
Every card here comes from a tutorial on this site – from an error we actually ran into while
setting things up on the test server. Type the error message (address already in use,
NXDOMAIN, Unauthorized) or describe the symptom in your own words.
400 findings from real setups
The sign-in bounces straight back and Outline shows “Authentication failed”.
Look at Authentik’s logs:
Read on: Outline: The Modern Team Wiki with an Authentik Login →docker compose logs server | grep -i grant. If it says Invalid grant_type for provider, the provider’s Grant types field is empty. In Authentik 2026.x Authorization Code has to be listed there explicitly; otherwise the sign-in aborts with invalid_request before the login mask even appears. Outline only logs OAuth error during authentication: The request is otherwise malformed – the actual cause is always on the Authentik side.After signing in you get redirect_uri back as an error.
The address stored in Authentik has to be exactly
Read on: Outline: The Modern Team Wiki with an Authentik Login →https://wiki.YOUR_DOMAIN/auth/oidc.callback, with the same name that URL= in Outline’s .env names. A different hostname, an extra slash or http instead of https is enough for a rejection. With matching mode Strict there is no leeway – that is the point.Outline shows no sign-in page any more and jumps straight to Authentik.
That is not a fault: with exactly one configured identity provider Outline skips its own selection page. As soon as you set up a second route it comes back. If you want to see the page, call it with a notice parameter, for example after a failed attempt.
Read on: Outline: The Modern Team Wiki with an Authentik Login →Uploads fail when you bind a host folder instead of using the volume.
Outline runs inside the container as
Read on: Outline: The Modern Team Wiki with an Authentik Login →nodejs with UID 1001 and cannot write into a root-owned folder – on hardened servers with umask 027 even less so. Either stay with the named volume, or run chown -R 1001:1001 on the directory. You can check with docker exec outline ls -la /var/lib/outline/data.Outline starts, but nobody can sign in, and the log is missing the line OIDC plugin registered.
Then at least one of the six
Read on: Outline: The Modern Team Wiki with an Authentik Login →OIDC_ variables is empty. Outline does not report this as an error – it simply starts without a sign-in route. Check with docker exec outline env | grep OIDC whether all values arrive; a common cause is a $ in the client secret, which Compose expands under environment:. With env_file: as used here that does not happen.Traefik answers with 502 Bad Gateway even though all four containers are running.
The nginx inside the web container listens on port 8000, not on 80, because it runs unprivileged. Set
Read on: Jitsi Meet: Your Own Video Conferences Without Zoom →traefik.http.services.jitsi.loadbalancer.server.port=8000. You can look it up with docker exec jitsi-web ss -lnt; the port actually in use is right there. The same error appears when traefik.docker.network=proxy is missing and Traefik picks up the container address from the internal meet.jitsi network, which it cannot reach itself.The web container starts but reports cp: cannot stat '/config/.': Permission denied and serves nothing.
The mounted folders under
Read on: Jitsi Meet: Your Own Video Conferences Without Zoom →/opt/jitsi/config belong to root while the containers run as UID 1000. A chown -R 1000:1000 /opt/jitsi/config and a restart fix it. On hardened servers with umask 027 this hits you every time, because newly created folders then get 0750.With two people everything works, from the third participant on nobody hears or sees anything.
That is the classic picture of a closed UDP port. It only surfaces now, because Jitsi runs two-person calls directly between the browsers and only uses the video bridge from three participants onwards. Check
Read on: Jitsi Meet: Your Own Video Conferences Without Zoom →ss -lunp | grep 10000 on the server and the inbound ACCEPT rule for UDP 10000 in both firewalls. The bridge’s logs show it too: docker compose logs jvb | grep -i 'ICE state' then shows transitions to Terminated without a connection ever being established.Everyone is in the room, but nobody hears or sees anybody.
That is almost always the media path, not the conference. Check
Read on: Jitsi Meet: Your Own Video Conferences Without Zoom →docker compose logs jvb | grep "static mapping" first. If there is no line with your public address, JVB_ADVERTISE_IPS is missing from the .env and the video bridge announces its container address to the browsers. If the address is right, the next suspect is UDP 10000 in the firewall, in both of them (the one on the server and the one at the provider). In the netcup SCP that means a policy of its own with an inbound ACCEPT rule on UDP 10000; a web template covering 80/443 does not include it.After docker compose down the moderator account is gone.
Prosody stores accounts under
Read on: Jitsi Meet: Your Own Video Conferences Without Zoom →/var/lib/prosody, and that directory is not mounted in the official template: the accounts disappear along with the container. The mount ./config/prosody/data:/var/lib/prosody:Z fixes it; afterwards the accounts live on the host under config/prosody/data/data/meet%2ejitsi/accounts/. An account that is already lost is simply created again.The “Waiting for a moderator” dialog stays up even after logging in.
Then the account does not exist in the domain Jitsi looks in. Registration happens against
Read on: Jitsi Meet: Your Own Video Conferences Without Zoom →meet.jitsi, the internal domain from the .env, not your real one. Check with docker exec jitsi-prosody prosodyctl --config /run/prosody/config/prosody.cfg.lua register NAME meet.jitsi PASSWORD: if the command reports “User already exists”, the domain is right and the password is wrong./_matrix/client/versions returns the Element start page instead of JSON.
Both routers listen on the same host and Traefik checked the wrong one first. Set
Read on: Matrix Part 2: Element, federation and admin →traefik.http.routers.synapse.priority=100 and …element.priority=10. Without explicit numbers Traefik sorts by rule length, and that result changes as soon as another rule joins. After the change docker compose up -d is enough; Traefik re-reads the labels straight away.The Element container does not start and reports cp: can't open '/app/config.json': Permission denied.
The
Read on: Matrix Part 2: Element, federation and admin →element-config.json on the host is not readable for the container. This happens reliably on servers with umask 027, because new files then get 0640 and no read bit for others. chmod 0644 /opt/matrix/element-config.json and restart. The same applies to every configuration file you hand into a container as a bind mount.Element hangs at “Confirm your digital identity”, and “Use recovery key” is greyed out.
You are signing in on another device and did not create a recovery key on the first one (step 5). If an old device is still signed in, take “Use another device” and confirm there. Otherwise only “Can’t confirm?” followed by your account password remains: Element then resets the identity; account, contacts and rooms stay, but messages from before remain unreadable. Create the recovery key right afterwards.
Read on: Matrix Part 2: Element, federation and admin →Signing in suddenly fails with M_LIMIT_EXCEEDED.
The answer contains
Read on: Matrix Part 2: Element, federation and admin →retry_after_ms, the waiting time in milliseconds. Synapse rate-limits login attempts per account and per IP; that hits you when you build several sessions in a row or test with scripts. For permanent operation it can be loosened through the rc_login block in homeserver.yaml, only you should not, because that exact brake is what stops guessing attacks.The device list and the logs show 172.x.x.x instead of the real visitor IP.
This only affects requests over IPv6, which, on a domain with an AAAA record, is most of them. The
Read on: Matrix Part 2: Element, federation and admin →proxy network is created with docker network create proxy in the Traefik tutorial, and that is an IPv4-only network. Docker then cannot rewrite an incoming IPv6 connection onto the container directly and sends it through a helper process that replaces the source address with the bridge gateway’s; over IPv4 the address is correct the whole time. The fix is a network with IPv6: docker compose down in every stack, then docker network rm proxy && docker network create --ipv6 --subnet fd00:cafe::/64 proxy and bring everything back up; the steps are in Reverse proxy with Traefik. Afterwards the real address shows up in X-Forwarded-For over IPv4 and IPv6.Synapse refuses to start and reports IncorrectDatabaseSetup: Database has incorrect collation.
The database was created with a language-dependent collation such as
Read on: Matrix: Your Own Chat Server with Synapse (Part 1) →de_DE.utf8; Synapse expects C. That cannot be changed afterwards, because the collation is fixed when the database is created. Delete the volume and start again with POSTGRES_INITDB_ARGS: "--encoding=UTF8 --lc-collate=C --lc-ctype=C". The error message offers allow_unsafe_locale as a way out; do not take it, because wrongly sorted indexes will bite you later during searches.The federation tester reports FederationOK: false even though the site loads in a browser.
Then the delegation is usually wrong. Check
Read on: Matrix: Your Own Chat Server with Synapse (Part 1) →curl -s https://YOUR_DOMAIN/.well-known/matrix/server. The answer has to contain the host including the port, something like {"m.server":"YOUR_DOMAIN:443"}. If you get a 404 here, serve_server_wellknown: true is missing from the configuration or another service intercepts the path. Also common: the server name in the delegation points at a host whose certificate is issued for a different name.The logs show Traefik’s IP for every access instead of the visitor’s.
x_forwarded: true is missing from the listeners block. Synapse only evaluates the forwarding headers when you explicitly allow it. Without the real source address you can neither trace abuse nor use fail2ban sensibly.Logging in fails with M_FORBIDDEN even though the password is right.
Check that you really are logging in at the right server: the user ID is
Read on: Matrix: Your Own Chat Server with Synapse (Part 1) →@name:server_name, not @name:host. If server_name and host differ and the client delegation is missing, your client ends up in the wrong place. curl -s https://YOUR_DOMAIN/.well-known/matrix/client has to return the homeserver’s base URL.The server runs but memory gets tight.
Synapse uses little while idle (a good 100 MB) but grows noticeably once you join large, heavily federated rooms, because it keeps track of their entire history. When it gets tight, the first remedy is to leave such rooms and then remove old events with the admin API’s cleanup functions. More memory is the other answer; a homeserver that takes part in real rooms is not happy on 1 GB.
Read on: Matrix: Your Own Chat Server with Synapse (Part 1) →vmstat shows a steady 100 percent id even though the site feels slow.
Then the
bottleneck is not on this server. Check the response time at the service directly instead of
through the domain – if the container answers fast and the browser still waits, it is the
path there: DNS, the TLS handshake or a congested network, not CPU or RAM.
Read on: When is your server too small? →Nothing at all in the kernel log, even though a container disappeared.
journalctl -k
only shows genuine OOM kills. If a service exits on its own, the reason is in its own log:
docker compose logs --tail 50 YOUR_SERVICE. An exit 137 without a matching kernel line is
usually a docker stop whose grace period ran out, not a memory problem.Load average is high but r and b are both 0.
You are reading the first
Read on: When is your server too small? →vmstat line.
That one is an average since boot and practically meaningless on a server with 80 days of
uptime. Use vmstat 1 5 and evaluate from the second line onwards.free -h reports almost no free memory, yet the server runs perfectly.
That is the
normal state. The kernel fills unused memory with file cache and hands it straight back when
somebody needs it. The column that matters is
Read on: When is your server too small? →available; free may happily sit near zero.Lots of reclaimable space, but docker image prune -a frees almost nothing.
Then the
images are still attached to stopped containers. Run
Read on: When is your server too small? →docker container prune first, then the
images – or do both at once with docker system prune -a, after checking that every stack
you want is actually running.The container restarts in a loop and reports error loading flags: flag needs an argument: --config.
While copying the
Read on: listmonk: Your Own Newsletter Server – Privacy-Friendly →command line the two single quotes after --config were lost – which happens easily when the command travels through several shell layers. Check what actually arrives with docker inspect listmonk --format '{{json .Config.Cmd}}': there has to be an empty argument after every --config. When in doubt, write the Compose file with an editor directly on the server instead of generating it through nested quoting.listmonk no longer starts and reports error reading SMTP config: decoding failed.
An invalid value is stored in the settings – a duration without a unit, for instance. The awkward part: the web interface is then unreachable, so you cannot fix it there. The settings live in the
Read on: listmonk: Your Own Newsletter Server – Privacy-Friendly →settings table; docker compose exec db psql -U listmonk -d listmonk gets you in and lets you UPDATE the smtp key back to a valid block. Then docker compose restart app.The database container does not start and talks about pg_ctlcluster.
That is the PostgreSQL 18 change: the mount must no longer point at
Read on: listmonk: Your Own Newsletter Server – Privacy-Friendly →/var/lib/postgresql/data but at /var/lib/postgresql. For an existing database, moving it is not enough – there you need pg_dump with the old major version and an import into the new one.The campaign stays on running and nothing is sent.
Then listmonk cannot reach the SMTP server.
Read on: listmonk: Your Own Newsletter Server – Privacy-Friendly →docker compose logs app | grep -i smtp shows why; often it is the wrong port (587 instead of 465 or the other way round), a wrong TLS setting, or a provider blocking outbound port 25. The local catcher from step 3 helps narrow it down: if sending there works, the problem is not listmonk.The mails arrive but land in spam.
That is not a listmonk problem. Check that SPF, DKIM and DMARC are right for the sender domain and that the sender address matches the domain you send through – how to do that is in email deliverability. Also avoid image-only HTML, and send to a small list first rather than writing to ten thousand addresses at once.
Read on: listmonk: Your Own Newsletter Server – Privacy-Friendly →The database container refuses to start and says something about pg_ctlcluster and directory names.
That is the PostgreSQL 18 change: from that major version the mount must no longer point at
Read on: HedgeDoc: Shared Markdown Notes in Real Time →/var/lib/postgresql/data but one level up at /var/lib/postgresql. The container also aborts when the volume is brand new and empty – the check hangs on the mount, not the content. For an existing database, moving the mount is not enough; there you first need a pg_dump with the old major version and an import into the new one.After moving the mount you get mkdir: can't create directory '/var/lib/postgresql/18/': Permission denied.
You are using a bind mount and the directory on the host belongs to root – the Postgres user inside the container cannot create anything in it. At the old path the image still fixed the permissions itself, at the new one it does not. Either hand the directory to the container user, or use a named volume as we do here, where Docker inherits the permissions from the image.
Read on: HedgeDoc: Shared Markdown Notes in Real Time →Links you send point at localhost or carry a port.
HedgeDoc does not build links from the
Read on: HedgeDoc: Shared Markdown Notes in Real Time →Host header but from its configuration. Set CMD_DOMAIN to your domain (name only, no https://, no path), CMD_PROTOCOL_USESSL to true and CMD_URL_ADDPORT to false. The container has to be restarted for a change to take effect.A guest edited your note even though CMD_ALLOW_ANONYMOUS_EDITS is false.
That option only works when
Read on: HedgeDoc: Shared Markdown Notes in Real Time →CMD_ALLOW_ANONYMOUS is false; with true it has no effect. What counts is the individual note’s permission: if it is on Freely, anyone with the link may write. Set CMD_ALLOW_ANONYMOUS to false, restart the container and set the note to Limited or Locked.Notes such as wp-json or xmlrpc.php show up that nobody created.
Those were bots looking for WordPress. With
Read on: HedgeDoc: Shared Markdown Notes in Real Time →CMD_ALLOW_ANONYMOUS: "true" together with CMD_ALLOW_FREEURL: "true", every request to a free address creates a new note. Set CMD_ALLOW_ANONYMOUS to false and restart the stack. The notes already created have no owner who could delete them in the interface; you remove them in the database: docker compose exec database psql -U hedgedoc -d hedgedoc -c 'DELETE FROM "Notes" WHERE "ownerId" IS NULL;' – their revisions go with them.An outsider only gets a redirect to the start page from the published link.
Then the note is on
Read on: HedgeDoc: Shared Markdown Notes in Real Time →Limited or Protected – both levels lock guests out completely, published versions included. For “read only, but for everyone”, Locked is the right choice. CMD_ALLOW_ANONYMOUS has nothing to do with it: the option only controls whether guests may create notes, not whether they may read them.Pingvin Share X: The page answers with 403 Forbidden.
The lock from step 1 does not let your address through. Usually the IPv6 is missing or has changed – look up both addresses again (see there), correct
Read on: Pingvin Share X: Sharing Large Files Without WeTransfer →sourcerange and restart with docker compose up -d.The links you send point to http://localhost:3000.
The App URL under Configuration → General is still on its default. Pingvin does not learn its public address by itself – the reverse proxy does not tell it. Enter
Read on: Pingvin Share X: Sharing Large Files Without WeTransfer →https://YOUR_DOMAIN and save; links you already sent have to be recreated.Every visitor shows up with the same IP in the access logs.
That is the address from the Docker proxy network, and
Read on: Pingvin Share X: Sharing Large Files Without WeTransfer →TRUST_PROXY: "true" is missing from the Compose file. Only with it does Pingvin evaluate the X-Forwarded-For header. But set it only when a proxy really is in front – without one, any client can invent its own source IP.A large upload aborts halfway through.
Check Max size under Configuration → Share first; the default is 1 GB, and the interface tells you before you even upload (“Maximum total upload size: 1 GB.”). If that is not it, Chunk size is the next lever: pieces smaller than the default 10 MB are more reliable on shaky connections, larger ones faster on stable ones.
Read on: Pingvin Share X: Sharing Large Files Without WeTransfer →Strangers are creating accounts on your instance.
Then Allow registration is still on – the shipping state. Switch it off under Configuration → Security & Access and delete the foreign accounts under Administration → User management. To verify:
Read on: Pingvin Share X: Sharing Large Files Without WeTransfer →curl -s -o /dev/null -w "%{http_code}\n" https://YOUR_DOMAIN/auth/signUp has to return 307 afterwards, not 200.You get logged out immediately after signing in.
Usually Secure cookies is enabled while you are visiting over
Read on: Pingvin Share X: Sharing Large Files Without WeTransfer →http:// – the browser then discards the cookie. Open the site over HTTPS. If you deliberately run Pingvin without TLS, the switch has to stay off; the setting says as much itself: “If enabled, the site will not function when accessed over HTTP.”eosctl compute vm delete reports nothing and the VM keeps running.
eos only deletes VMs that
are powered off and doesn’t say so. Run
Read on: Automating netcup eos with eosctl and OpenTofu →eosctl compute vm power-off first, wait until
power_state is stopped, then delete (step 6).exec doesn’t work right after creation.
started only means the VM is running. The agent
exec talks to needs another half minute – wait until agent_ready is true (step 4).Only the first of several commands returns output.
The inner quotes in
Read on: Automating netcup eos with eosctl and OpenTofu →bash -c are single
quotes. Use escaped double quotes as in step 5.OpenTofu aborts with a permission error while creating resources.
Every credential can read,
but writing needs a role. This setup needs
Read on: Automating netcup eos with eosctl and OpenTofu →compute:network-manager and compute:vm-manager.
Also check the client credentials list to see whether it has expired, and create a new one if
necessary.tofu init can’t find the provider.
The
Read on: Automating netcup eos with eosctl and OpenTofu →source must include the hostname:
dl.eoscloud.io/eos/eoscloud. Without it, OpenTofu searches its own registry, where the provider
doesn’t live.The login fails with the correct password even though the hash is right.
Then the hash is probably in a
Read on: code-server: VS Code in the Browser on Your Own Server →.env file or under environment:. Docker Compose interpolates $ characters in values from env files too, turning $argon2id$v=19$m=65540,... into =19=65540,t=3,p=4/Ntxaqbs... – and it only warns with The "argon2id" variable is not set. Either double every $ to $$, or do it the way we did and put the hash in config.yaml, where Compose never looks.Traefik answers with 401 even though you typed the right BasicAuth password.
Same cause, different place: every
Read on: code-server: VS Code in the Browser on Your Own Server →$ of the bcrypt hash in the basicauth.users label has to be doubled. Check what actually arrives with docker compose config – a mangled hash there means the doubling is missing.The terminal says bash: python3: command not found.
The official image contains only the editor, no language runtimes –
Read on: code-server: VS Code in the Browser on Your Own Server →git, curl and sudo are there, nothing more. Build the derived image from step 2 and restart with docker compose up -d --build. Installing into the running container only helps until the next restart.code-server cannot save a file and reports Permission denied.
The folders under
Read on: code-server: VS Code in the Browser on Your Own Server →projekte belong to root instead of UID 1000. That happens as soon as you create a directory as root on the host. chown -R 1000:1000 /opt/code-server/projekte fixes it; the habit worth building is to create new projects from inside the editor rather than on the host.sudo in the terminal aborts with The "no new privileges" flag is set.
That is not a defect but the effect of
Read on: code-server: VS Code in the Browser on Your Own Server →security_opt: no-new-privileges:true. Do not remove that line – it is the only reason the bundled coder ALL=(ALL) NOPASSWD:ALL in /etc/sudoers.d/nopasswd is useless to anyone. Whatever you need permanently belongs in the Dockerfile.Outgoing mail runs into a timeout on port 25, 465 or 587.
That isn’t your configuration but
netcup’s default policy “netcup Mail block”. Take it off the server in the SCP under
Firewall → Policies – no ticket needed, see
netcup firewall setup.
Read on: 100 days of netcup: what nobody tells you beforehand →DNS or time synchronisation doesn’t work, even though everything outbound is allowed.
The
netcup firewall is stateless for UDP and doesn’t automatically let reply packets through. Create
inbound rules for source port 53 (DNS) and 123 (NTP).
Read on: 100 days of netcup: what nobody tells you beforehand →A service responds on the server, but not from outside.
Then the SCP firewall is blocking it,
not the one on the server. Only 22, 80 and 443 are open inbound; every additional port needs its
own policy. Test with
Read on: 100 days of netcup: what nobody tells you beforehand →curl from another machine, not from localhost.The disk is full, but you can’t find any large files.
Check Docker:
Read on: 100 days of netcup: what nobody tells you beforehand →docker system df shows
you how much is in images and how much of it is disposable. In our case it was 68 GB out of
73 GB used. docker image prune -a cleans up.A container is killed by the kernel (OOM), even though the server has headroom.
Then a
memory limit of the container is kicking in, not that of the host. In that case the log shows
Read on: 100 days of netcup: what nobody tells you beforehand →constraint=CONSTRAINT_MEMCG. This happened to us exactly once – raise the service’s limit
before you think about a bigger server.Requests from outside still get 200 instead of 403.
Almost always the middleware is defined but not attached to the router. The two labels have different jobs:
Read on: Make services reachable only over VPN →traefik.http.middlewares.vpn-only.ipallowlist.sourcerange=… creates it, traefik.http.routers.YOURROUTER.middlewares=vpn-only uses it. Leave out the second line and everything starts without errors while the service sits wide open – with no error message whatsoever. The @docker suffix is optional as long as middleware and router come from the same provider.Even from inside the VPN you get 403.
Then Traefik sees a different source IP than the VPN client’s. Check with
Read on: Make services reachable only over VPN →curl -s https://YOUR_DOMAIN/ | grep X-Real-Ip against a whoami container: if it shows a Docker-internal address such as 172.19.0.x or a CDN’s IP, there is another proxy in front. In that case you have to tell Traefik via forwardedHeaders.trustedIPs which predecessor it may believe – without that setting it does not evaluate the header at all.Inside the VPN the name still resolves to the public IP.
The client is not using AdGuard. Check
Read on: Make services reachable only over VPN →cat /etc/resolv.conf first – if it does not say nameserver 10.8.0.1, then DNS = 10.8.0.1 did not take effect. wg-quick needs a tool that can change the resolver configuration: either resolvconf from the openresolv package or resolvectl from the systemd-resolved package. A minimal Debian 13 ships neither, and then the line does nothing. Whether AdGuard itself answers correctly is a separate check: dig +short @10.8.0.1 YOUR_DOMAIN.The certificate suddenly stops renewing.
The ACME fetch needs the public path. If you deleted the A record in the meantime, closed port 80, or accidentally applied the allowlist globally on the
Read on: Make services reachable only over VPN →web entrypoint, Let’s Encrypt can no longer reach the challenge. docker compose logs traefik | grep -i acme shows the failure – but only shortly before expiry, not immediately.The service answers inside the VPN, but only sometimes.
That is usually address-family ordering: as long as the name still returns an AAAA answer, the client tries IPv6 first – and lands outside the tunnel on the
Read on: Make services reachable only over VPN →403. Create the DNS rewrite for IPv4 only; AdGuard then returns no AAAA for that name at all, and dig +short AAAA @10.8.0.1 YOUR_DOMAIN has to stay empty.You put a public IPv6 address into the allowlist and still get 403.
Traefik compares against the address it actually sees – and over IPv6 that is the bridge gateway’s, as long as the
Read on: Make services reachable only over VPN →proxy network was created without IPv6. Your real address never enters the comparison. Check it with curl -s -6 https://YOUR_DOMAIN/ | grep X-Forwarded-For from the allowed network: if it says 172.x.x.x, recreate the proxy network with --ipv6 (see Reverse proxy with Traefik). For the VPN case in this tutorial it makes no difference, because WireGuard runs over IPv4 here.SSH reports Connection refused although IP and ACL are right.
No SSH server is running on
the VM – the cloud images don’t ship one either. Open the web console, install it with
Read on: netcup eos hands-on: the new cloud in preview →apt install openssh-server and add the package to your cloud-init file for future VMs (section “Cloud-init: the SSH server is missing”).The key is refused, the log says account is locked.
Your cloud-init file contains
Read on: netcup eos hands-on: the new cloud in preview →ssh_pwauth. That produces a one-line sshd_config without UsePAM yes. Check with
wc -l /etc/ssh/sshd_config – if it says 1, delete the file in the web console, reinstall the
package with apt install --reinstall -o Dpkg::Options::=--force-confmiss openssh-server and
restart the service with systemctl restart ssh. Debian’s full configuration is then back on disk.The VM has a public IP but isn’t reachable.
The ACL rule is missing. Without a rule, all inbound
traffic is blocked; create an allow rule for the port with the VM’s internal IP as destination.
Read on: netcup eos hands-on: the new cloud in preview →Failed to create ACL Rule right after saving.
The destination is entered as
Read on: netcup eos hands-on: the new cloud in preview →@vm-name. Enter
the VM’s internal IP instead, shown on its detail page.A default IP can’t be attached to the VM.
The two public addresses every network brings along
are reserved for outbound traffic and port forwards. Create a separate public IP in the same network
and attach that one.
Read on: netcup eos hands-on: the new cloud in preview →Headscale doesn’t start and reports headscale now requires a new noise.private_key_path field.
The
Read on: Headscale: Your Own Tailscale Network →noise: block with private_key_path: /var/lib/headscale/noise_private.key is missing from config.yaml (step 1). You don’t have to create the key yourself, Headscale does that on startup.Headscale restarts in a loop, the log says loading policy: open /etc/headscale/policy.json: no such file or directory.
policy.path points to a file that doesn’t exist yet. Create the allow-everything file from step 1 or your real rules from step 7 right away.apt-get update reports The repository 'https://pkgs.tailscale.com/...' is not signed.
Look at the line above it, which usually says
Read on: Headscale: Your Own Tailscale Network →Failed to parse keyring ... Permission denied (os error 13). The cause is a stricter UMASK (such as 027) on the system: curl -o then creates the key with mode 0640, and apt verifies signatures as the unprivileged user _apt, which cannot read the file. chmod 0644 /usr/share/keyrings/tailscale-archive-keyring.gpg /etc/apt/sources.list.d/tailscale.list fixes it immediately.Headscale refuses to start and reports server_url cannot use the same domain as base_domain.
dns.base_domain and the domain in server_url overlap. Headscale rejects that because the control server itself would then be resolved through MagicDNS and could make itself unreachable. Pick a separate, non-public zone such as home.internal for base_domain and validate the file before every restart with docker compose exec headscale headscale configtest.The logs say listening without TLS but ServerURL does not start with http://.
That is not a malfunction but the normal state behind a reverse proxy: Headscale speaks HTTP, Traefik handles TLS. You recognise a real problem by
Read on: Headscale: Your Own Tailscale Network →curl https://YOUR_DOMAIN/health not returning {"status":"pass"} – in that case it is Traefik, not Headscale.A client will not connect and hangs during registration.
Check the client version first with
Read on: Headscale: Your Own Tailscale Network →tailscale version: Headscale 0.29 rejects anything below 1.80, and the distribution packages of some LTS systems are older than that. If the version is fine, the next suspect is the pre-auth key – the default lifetime is one hour, and preauthkeys list shows you in the Expiration column whether it is still valid.A subnet route is approved and installed on the client, yet the destination stays unreachable.
If the target network is a Docker network on the same host, Docker blocks the traffic itself. Its filter chain contains
Read on: Headscale: Your Own Tailscale Network →-A DOCKER ! -i br-XXXX -o br-XXXX -j DROP, and packets arriving via tailscale0 hit exactly that rule. For container networks you therefore do not use a subnet route but publish the service through the reverse proxy as usual. For real LANs, check instead whether net.ipv4.ip_forward=1 is set on the subnet router.After setting UMASK 027 a service no longer starts and reports “Permission denied” on its own configuration file.
The new umask applies from your next login onwards, and everything you create with
Read on: How Secure Is My Server? A Self-Audit With Lynis →> or cat > after that gets mode 0640 instead of 0644. Services running under their own user – systemd-timesyncd uses DynamicUser, for instance – can then no longer read the file. The journal shows Failed to open ...: Permission denied. Set the permissions explicitly for configuration files that are not owned by root: chmod 0644 /etc/systemd/timesyncd.conf.d/99-lynis.conf.After applying the sysctl values none of the containers have network access.
Then
Read on: How Secure Is My Server? A Self-Audit With Lynis →net.ipv4.conf.all.forwarding ended up at 0. Lynis suggests it, but without IP forwarding Docker cannot pass packets between the container network and the outside world. Remove the line from /etc/sysctl.d/99-lynis.conf and reset the value immediately with sysctl -w net.ipv4.conf.all.forwarding=1 – restarting Docker alone will not help.systemd-timesyncd did not synchronized the time recently persists even though timedatectl reports NTPSynchronized=yes.
Lynis does not check the clock but the age of
Read on: How Secure Is My Server? A Self-Audit With Lynis →/run/systemd/timesync/synchronized, and warns beyond 2048 seconds. Since systemd raises its poll interval to exactly 2048 seconds when the clock is stable, the test inevitably runs into the warning. Either lower PollIntervalMaxSec as shown in step 4, or add the test to custom.prf – but do not just ignore it, or you will miss the day time synchronisation really breaks.Lynis reports Consider hardening SSH configuration ten times and never says what it means.
The screen output drops the details. They are in the third field of
Read on: How Secure Is My Server? A Self-Audit With Lynis →grep "^suggestion\[\]=SSH-7408" /var/log/lynis-report.dat – that gives you the parameter and target value for every line.After installing auditd a finding was added instead of removed.
ACCT-9630 reports a running audit daemon with an empty ruleset. That is intended: auditd without rules burns resources without logging anything. Put rules under /etc/audit/rules.d/ and load them with augenrules --load – or uninstall auditd again if you are not going to read the log.The container won’t start and reports Operation not permitted.
You dropped one
capability too many. The message almost always names the system call –
Read on: Hardening Docker containers with least privilege →chown(...) failed means CHOWN, setgid means SETGID. Hand back exactly that one
(cap_add: [CHOWN]) and restart; work your way towards the minimum instead of adding
several capabilities on suspicion.The container is Up according to docker compose ps but doesn’t answer.
Up only
means PID 1 is alive – not that the application is working. With nginx the workers die
without SETUID/SETGID while the master keeps running. Check with docker exec CONTAINER ps -o pid,user,comm whether there is more than one process, and look at the
log: docker compose logs | grep -iE "alert|emerg".Read-only file system at startup.
The application needs a writable directory you
haven’t provided as
Read on: Hardening Docker containers with least privilege →tmpfs yet. The error message names the path; add it under tmpfs:.
Careful: real data never belongs in a tmpfs – that is RAM and gone on restart. Keep
using a volume for that.The page returns 403 Forbidden, the log says is forbidden (13: Permission denied).
nginx runs as UID 101 and isn’t allowed to read the files in the mounted directory – typical for
servers with
Read on: Hardening Docker containers with least privilege →UMASK 027, where root creates new files without read permission for others. Check
with ls -l and fix with chmod -R a+rX site.Permission denied in the tmpfs even though read_only looks right.
A
Read on: Hardening Docker containers with least privilege →tmpfs belongs
to root by default. If you set user:, the mount needs the UID:
/var/cache/nginx:uid=101,gid=101. Find the right UID with docker run --rm YOUR_IMAGE id USERNAME.The container is killed without warning and docker inspect shows ExitCode 137.
That
is the OOM killer:
Read on: Hardening Docker containers with least privilege →mem_limit is too tight. Measure the real demand in operation with
docker stats --no-stream and set the limit a little above it. Leaving the limit out
entirely is the worse option – then the container may take the server down with it.No code prompt appears at all, the login works as before.
Then
Read on: Securing SSH with Two-Factor Authentication (TOTP) →KbdInteractiveAuthentication is
still no – the default on Debian 13. Check what really applies with
sudo sshd -T | grep kbdinteractive, and note that files in /etc/ssh/sshd_config.d/ are read in
alphabetical order and the first setting wins.After the key you are also asked for the password.
Not a bug but the consequence of UsePAM yes:
keyboard-interactive runs the whole PAM stack, including @include common-auth. If you only want key
- code, comment that line out – with the consequence from the warning in step 7.
The code is rejected even though the app shows it right now.
Usually the server clock has drifted.
TOTP tolerates only a few seconds. Check
Read on: Securing SSH with Two-Factor Authentication (TOTP) →timedatectl – it must say System clock synchronized: yes;
otherwise enable NTP. Second possibility: you used the same code shortly before and DISALLOW_REUSE
forbids that. This also applies if the previous attempt only failed at the password – the code
was correct and is therefore used up. The same code is then rejected even with the correct
password; only the next one goes through. So simply wait for the next one.After three failed attempts nothing works any more.
That is the rate limit from
Read on: Securing SSH with Two-Factor Authentication (TOTP) →-r 3 -R 30: three
attempts per 30 seconds. Every round counts: after a wrong password the SSH client asks again up to
three times, and that alone exhausts the limit. Wait a moment instead of typing on.One user gets in without a code.
Either their
Read on: Securing SSH with Two-Factor Authentication (TOTP) →~/.google_authenticator is missing and nullok
lets them pass, or a Match block with different AuthenticationMethods applies to them.
sudo sshd -T -C user=NAME,host=localhost,addr=127.0.0.1 | grep authenticationmethods shows what really
applies to them.Phone lost, no scratch codes.
Then only an access path that does not go through SSH helps: the
provider’s VNC console. Log in there and delete the user’s file (
Read on: Securing SSH with Two-Factor Authentication (TOTP) →rm ~/.google_authenticator) – with
nullok they get back in without a code, without it you end up with an account that has no second
factor and needs to be set up again.Mail to the outside hangs, the logs show timeouts on port 25.
This isn’t the software, it’s
the host: netcup’s default policy “netcup Mail block” blocks 25, 465 and 587 outbound. You take
the policy off the server yourself in the SCP under Firewall → Policys – no support case, no
ticket. Affects Stalwart and Mailcow equally, see
netcup firewall setup.
Read on: Stalwart or Mailcow? Two mail servers compared →The mail arrives but lands in spam everywhere.
Then reverse DNS (PTR), SPF, DKIM or DMARC are
missing. This too is independent of the product and described step by step in
email deliverability.
Read on: Stalwart or Mailcow? Two mail servers compared →Mailcow won’t start, the logs report address already in use for port 80 or 443.
A reverse
proxy is already running on the server and Mailcow’s own nginx wants the same ports. Either give
Mailcow the host to itself, or bind its nginx to a local port as shown under “What it costs to move in next to a
reverse proxy” and put it behind the proxy.
Read on: Stalwart or Mailcow? Two mail servers compared →After the Mailcow setup all the other containers are suddenly gone.
On an IPv6 host
Read on: Stalwart or Mailcow? Two mail servers compared →generate_config.sh created /etc/docker/daemon.json and restarted Docker. That’s intended
behaviour and prevents an open relay, but it hits the whole host. Containers with
restart: unless-stopped come back by themselves, the rest you start by hand.The mail client warns about a self-signed certificate CN=rcgen self signed cert.
Stalwart
is still serving its placeholder. Check
Read on: Stalwart or Mailcow? Two mail servers compared →docker compose logs traefik-certs-dumper first: if it
says /traefik/acme.json is not a file, the path in the dumper doesn’t point at the directory
holding Traefik’s acme.json. If the files are in the volume, only the reload is missing –
Actions → Reload → TLS certificates or a Stalwart restart; registered certificates are served
only after that.Containers get killed by the kernel after a short while (OOM).
The server is too small for the
stack you chose. With Mailcow and its 18 containers this happens considerably earlier than with
Stalwart; as a first measure turn ClamAV off in
Read on: Stalwart or Mailcow? Two mail servers compared →mailcow.conf with SKIP_CLAMD=y, since the
virus scanner is the biggest memory eater.The script aborts while looking up the flows with IndexError: list index out of range.
This
only happens right after a fresh installation:
Read on: Authentik Part 2: Connecting Apps – Forward Auth & OIDC →/-/health/ready/ already reports 200 while the
worker is still importing the bundled flows. At that moment there is often only one flow;
all 15 are there 20 to 30 seconds later. Wait briefly and run it again.The request redirects to http://localhost/application/o/authorize/….
The embedded outpost does not
know its public address: the
Read on: Authentik Part 2: Connecting Apps – Forward Auth & OIDC →authentik_host field is empty. Set it to https://YOUR_DOMAIN/ (step 3) –
before that every user lands on a dead page.Traefik answers with 500, or no redirect happens at all.
Then the middleware cannot reach the
outpost. The
Read on: Authentik Part 2: Connecting Apps – Forward Auth & OIDC →address has to be resolvable from Traefik’s point of view – so the service name from
the compose file, which Docker registers as an alias on the shared network
(http://server:9000/outpost.goauthentik.io/auth/traefik), not localhost. From the Traefik folder,
check with docker compose exec traefik wget -S -qO- http://server:9000/-/health/live/; the endpoint
returns an empty body, hence the -S – what you need to see is HTTP/1.1 200 OK.The service is protected but does not know the user.
authResponseHeaders is missing from the
middleware. Without that list Traefik discards the identity headers from Authentik’s response – the login
works, but the application sees nothing.After signing in you end up in a redirect loop.
Usually
Read on: Authentik Part 2: Connecting Apps – Forward Auth & OIDC →external_host does not match the address
actually being called (http instead of https, with or without a subdomain). It has to be exactly the URL
users open the service at.The OIDC login fails with „redirect_uri mismatch".
Authentik checks the callback address strictly.
Enter exactly the URI the application sends – for Grafana e.g.
Read on: Authentik Part 2: Connecting Apps – Forward Auth & OIDC →https://GRAFANA_DOMAIN/login/generic_oauth. A missing trailing slash is enough to break it.All signed-in users get in everywhere.
Without a binding to a group an application is open to every
authenticated user. Attach a group binding to the application (step 8) and verify with an account that
is not in the group.
Read on: Authentik Part 2: Connecting Apps – Forward Auth & OIDC →Authentik: The page responds with 403 Forbidden.
The lock from step 2 doesn’t let your address through.
Usually the IPv6 is missing or has changed – look up both addresses again (see there), correct
Read on: Authentik: single sign-on for all services (Part 1) →sourcerange and restart with docker compose up -d.The interface returns Internal Server Error while the container counts as healthy.
Then
Authentik cannot read its template directories. Typical for servers with
Read on: Authentik: single sign-on for all services (Part 1) →UMASK 027: mkdir
creates drwxr-x--- there – and the container runs as user 1000, which cannot enter them. The log says PermissionError: [Errno 13] Permission denied: '/templates/if/error.html'. Fix it with chmod 755 media certs custom-templates in the
stack directory and restart.The page answers with 404 for minutes even though the containers are running.
On the first start over
550 database migrations run; while they do,
Read on: Authentik: single sign-on for all services (Part 1) →/-/health/ready/ returns 404 as well. On the VPS 1000 that was
over after 105 seconds, the setup flow another ten to 25 seconds later. docker logs -f authentik-server-1 shows the progress.Calling the setup flow gives „Request has been denied."
The setup flow cannot be opened directly via
Read on: Authentik: single sign-on for all services (Part 1) →/if/flow/initial-setup/. Go to the root address https://YOUR_DOMAIN/, from where Authentik redirects
correctly.The „workers" tile shows 0.
The
Read on: Authentik: single sign-on for all services (Part 1) →worker container is not running or cannot reach the database.
Without it, emails, scheduled tasks and outpost management are left undone – with no error message in the
interface. Check docker compose ps and the worker’s logs.Traefik answers with 404.
Usually
Read on: Authentik: single sign-on for all services (Part 1) →traefik.http.services.authentik.loadbalancer.server.port=9000 is missing. The container listens on
9000; port 9443 is Authentik’s own HTTPS, which we deliberately do not use.After a rebuild all sessions are invalid or the login fails.
Then the
Read on: Authentik: single sign-on for all services (Part 1) →AUTHENTIK_SECRET_KEY changed –
for example because the .env was regenerated. The key has to stay the same for the lifetime of the
installation; restore it from your backup.The username doesn’t match.
The account created during setup is called
Read on: Authentik: single sign-on for all services (Part 1) →akadmin, not your email
address. If you want to log in with the address, allow that in the identification stage of the login
flow.The logs say „middleware … does not exist" and the service answers with 404.
Almost always the
provider suffix is missing: a middleware defined in the file provider is called
Read on: Hardening Traefik: security headers, rate limit & more →name@file from the
perspective of Docker labels. Without the suffix Traefik looks for it among the Docker labels – and
finds nothing. The same applies the other way round for name@docker.BasicAuth rejects the correct password.
The
Read on: Hardening Traefik: security headers, rate limit & more →$ characters in the bcrypt hash were interpreted as
variables by Docker Compose. In Compose they have to be doubled ($$2y$$05$$…). docker compose config shows the value that really arrives.The rate limit doesn’t seem to work.
Sequential
Read on: Hardening Traefik: security headers, rate limit & more →curl calls are too slow: every process opens a
new connection, so you stay below the limit. Test in parallel, e.g. with
seq 40 | xargs -P 8 -I{} curl … – then the 429s appear.After setting the IP allowlist you get 403 yourself.
Most common reason: you entered only your
IPv4 but connect over IPv6. Compare
Read on: Hardening Traefik: security headers, rate limit & more →curl -4 and curl -6 against your domain and enter both
address families (see step 5). Second reason: Traefik does not see your IP but that of the
proxy in front of it (Cloudflare, load balancer). Check with traefik/whoami what X-Forwarded-For
contains, and use ipallowlist.ipstrategy.depth for multi-stage setups.The browser still refuses plain HTTP even though you fixed the configuration.
That is HSTS, not a
bug: the browser remembers
Read on: Hardening Traefik: security headers, rate limit & more →max-age and enforces HTTPS even when your server no longer offers it. A
private window or a different browser helps for testing – and that is why the warning about preload
exists above.Dockge: The page answers with 403 Forbidden.
The restriction from step 2 doesn’t let your address
through. Usually the IPv6 is missing or has changed – look up both addresses again (see there),
correct
Read on: Dockge: Manage Compose Stacks in the Browser →sourcerange and restart with docker compose up -d.Traefik answers with 404 although the container is healthy.
Usually
Read on: Dockge: Manage Compose Stacks in the Browser →traefik.http.services.dockge.loadbalancer.server.port=5001 is missing. Inside the container Dockge
listens on 5001; without that line Traefik guesses. Also check that the container is attached to the
proxy network.The deployment aborts with „no such file or directory".
The host and container paths of the stacks
directory do not match. It must be mounted as
Read on: Dockge: Manage Compose Stacks in the Browser →/opt/stacks:/opt/stacks with
DOCKGE_STACKS_DIR=/opt/stacks – Dockge has the host’s Docker daemon do the work, and that daemon
only knows host paths.A stack is visible but all buttons are missing.
Then it lives outside
Read on: Dockge: Manage Compose Stacks in the Browser →/opt/stacks and Dockge
shows „This stack is not managed by Dockge." Move the folder as in step 7 – Dockge neither adopts it
by itself nor makes a copy.The stack name is rejected.
Only lowercase letters, digits, hyphens and underscores are allowed,
because they become the folder and Compose project name.
Read on: Dockge: Manage Compose Stacks in the Browser →My App fails with
Stack name can only contain [a-z][0-9] _ - only, my-app works.After a restart the login is gone.
Then
Read on: Dockge: Manage Compose Stacks in the Browser →./data was not mounted persistently – that is where the
database and JWT secret live. Check that /opt/dockge/data exists and is bound in the Compose file.The interface is in the wrong language.
Dockge follows the browser and falls back to English for
unknown combinations; the settings let you pin the language.
Read on: Dockge: Manage Compose Stacks in the Browser →Audiobookshelf: The page responds with 403 Forbidden.
The lock from step 3 doesn’t let your address through.
Usually the IPv6 is missing or has changed – look up both addresses again (see there), correct
Read on: Audiobookshelf: Self-Host Audiobooks & Podcasts →sourcerange and restart with docker compose up -d.The library stays empty after you create it.
The first scan does not run automatically – that is
not a bug but how Audiobookshelf behaves. In the library view, click Scan Library. If it stays
empty afterwards, check with
Read on: Audiobookshelf: Self-Host Audiobooks & Podcasts →docker compose exec audiobookshelf ls -R /audiobooks whether the
container sees the files at all, and with ls -ln /opt/audiobookshelf/audiobooks that everything is
owned by UID 1000.Four MP3 files become four audiobooks instead of four chapters.
The files sit directly in the
author folder instead of a shared title folder. Audiobookshelf groups by
Read on: Audiobookshelf: Self-Host Audiobooks & Podcasts →Author/Title/ – move the
files into a subfolder named after the book and scan again.Traefik answers with 404 even though the container is running.
Usually
Read on: Audiobookshelf: Self-Host Audiobooks & Podcasts →traefik.http.services.abs.loadbalancer.server.port=80 is missing. Inside the container
Audiobookshelf listens on 80; without that line Traefik guesses and misses. Also check that the
container really is attached to the proxy network.The address jumps to /audiobookshelf/.
That is normal: the frontend ships with this fixed
router path, and
Read on: Audiobookshelf: Self-Host Audiobooks & Podcasts →ROUTER_BASE_PATH changes nothing at runtime because the path is baked into the
image. https://YOUR_DOMAIN remains a valid entry point.After switching devices the language is back to English.
The language choice lives locally in the
browser, not on the account. Set it once per device via your username →
Read on: Audiobookshelf: Self-Host Audiobooks & Podcasts →Language.The podcast is not found.
The search queries the iTunes catalogue; a typo or a missing entry
there leads to „no search results". Use the podcast’s RSS URL instead – the same field accepts both.
Read on: Audiobookshelf: Self-Host Audiobooks & Podcasts →WordPress: The page answers with 403 Forbidden.
The restriction from step 2 doesn’t let your address through. Usually the IPv6 is missing or has changed – look up both addresses again (see there), correct
Read on: Running WordPress Cleanly with Docker & Traefik →sourcerange and restart with docker compose up -d.Redirect loop (ERR_TOO_MANY_REDIRECTS) or mixed-content warnings.
The HTTPS detection is missing. Check that the
Read on: Running WordPress Cleanly with Docker & Traefik →WORDPRESS_CONFIG_EXTRA block with HTTP_X_FORWARDED_PROTO and the $$ signs is set exactly (see the warning in step 2), and restart the WordPress container.WordPress won’t start, reports “Error establishing a database connection”.
Usually a race condition or a password mismatch. Check that
Read on: Running WordPress Cleanly with Docker & Traefik →depends_on: condition: service_healthy is set and WORDPRESS_DB_PASSWORD matches MARIADB_PASSWORD exactly. Logs: docker compose logs db.The first start fails even though everything runs later.
The database needs a few seconds to initialize on the very first start. The health check covers this; without it, another
Read on: Running WordPress Cleanly with Docker & Traefik →docker compose up -d helps.Media uploads fail for large files.
PHP limits the upload size. Create your own
Read on: Running WordPress Cleanly with Docker & Traefik →uploads.ini and mount it to /usr/local/etc/php/conf.d/ with e.g. upload_max_filesize = 64M and post_max_size = 64M.After a domain change the site points nowhere.
WP_HOME/WP_SITEURL are hard-wired in the Compose file – for a new domain, change them there and restart the container (the values override the database setting).The page doesn’t load, Traefik answers with a 404, even though the container is running.
The health check isn’t
Read on: linkding: Self-Host Your Bookmarks →healthy yet (see step 2). Check with docker compose ps or docker inspect -f '{{.State.Health.Status}}' linkding-linkding-1; if it stays unhealthy, docker compose logs linkding tells you why.The login form answers with Forbidden (403) CSRF verification failed.
The login page itself loads normally, but Django didn’t consider the request’s origin trustworthy – typical when a proxy in front of Traefik rewrites the
Read on: linkding: Self-Host Your Bookmarks →Host header or linkding runs under a sub-path. Add LD_CSRF_TRUSTED_ORIGINS: https://YOUR_DOMAIN (with https://, without a path and without a trailing slash) and run docker compose up -d.Title and description aren’t fetched automatically.
The target page blocks automated access or responds too slowly. Enter both by hand or switch the bookmarklet to detection in the browser (step 5).
Read on: linkding: Self-Host Your Bookmarks →The admin account wasn’t created.
LD_SUPERUSER_NAME and LD_SUPERUSER_PASSWORD only take effect on the first start with an empty database. If data/db.sqlite3 already exists, a later change does nothing. Create the account afterwards: docker compose exec linkding python manage.py createsuperuser.The API or the extension answers with 401.
Either the token is missing or it’s wrong:
Read on: linkding: Self-Host Your Bookmarks →{"detail":"Authentication credentials were not provided."} means the Authorization header never arrived, {"detail":"Invalid token."} means the token doesn’t match. Since a token is only shown once, creating a new one under Settings → Integrations is faster than hunting for the old one. Enter exactly https://YOUR_DOMAIN as the server, with no path after it.Navidrome: The page responds with 403 Forbidden.
The lock from step 3 doesn’t let your address through. Usually the IPv6 is missing or has changed – look up both addresses again (see there), correct
Read on: Navidrome: Stream Your Own Music Like Spotify →sourcerange and restart with docker compose up -d.The library stays empty.
Either there are no files in the mounted
Read on: Navidrome: Stream Your Own Music Like Spotify →music folder, or the permissions are wrong. Check: docker compose logs --no-log-prefix | grep "Scanner:" shows tracksImported. If it’s 0 everywhere, check the path and that the music folder is owned by UID 1000 (see Users & permissions).Tracks appear unsorted or without cover art.
The files’ metadata is incomplete – Navidrome sorts by tags, not by filenames. What it actually reads from a file is shown by
Read on: Navidrome: Stream Your Own Music Like Spotify →docker compose exec navidrome /app/navidrome inspect "/music/Artist/Album/Track.mp3": under rawTags you get the tags exactly as they sit in the file. If album or albumartist are missing there, re-tag the files (e.g. with Picard) and let Navidrome rescan.New music doesn’t show up.
The scan only runs hourly (
Read on: Navidrome: Stream Your Own Music Like Spotify →ND_SCANNER_SCHEDULE). Trigger an immediate scan via the refresh icon in the top right of the web interface, or wait for the next interval. If the files were just uploaded, what’s usually missing is the chown -R 1000:1000 from step 2.The app won’t connect.
Almost always the server URL: it must be
Read on: Navidrome: Stream Your Own Music Like Spotify →https://YOUR_DOMAIN (with https://, no path). If the ping.view call from step 8 answers cleanly, it’s the credentials – since version 0.64.1 Navidrome additionally throttles repeated failed logins through the Subsonic API, so after a few typos a short break helps.Playback stutters on large FLAC files over mobile.
The bandwidth isn’t enough for the original. Set a transcoding profile and a ceiling for your app’s player (step 9) – the entry only appears under Players after the app has connected once.
Read on: Navidrome: Stream Your Own Music Like Spotify →Container won’t start: “unable to open database file”.
DB_NAME: /data/hc.sqlite is missing or the data folder isn’t owned by UID 1000. Set the path and chown -R 1000:1000 /opt/healthchecks/data (see the warning in step 2).The container shows Restarting and the domain returns 404.
docker compose logs shows (hc.api.E002) The hostname in settings.SITE_ROOT is not found in settings.ALLOWED_HOSTS. Put exactly the hostname from SITE_ROOT into ALLOWED_HOSTS – without https:// – and restart with docker compose up -d.Login fails with 403 (CSRF error on submit).
Healthchecks then treats the request as plain HTTP, and Django rejects the form because the
Read on: Healthchecks: monitor cron jobs and backups →https://… origin doesn’t match. The image detects HTTPS via the X-Forwarded-Proto header that Traefik sends – if it’s missing, for instance behind a differently configured proxy, you get this error. A CSRF_TRUSTED_ORIGINS variable doesn’t help: Healthchecks doesn’t read it.The check won’t turn “green” even though the job runs.
Check whether the
Read on: Healthchecks: monitor cron jobs and backups →curl ping actually runs and hits the right UUID: curl -v https://YOUR_DOMAIN/ping/UUID should return OK. On the detail page the log shows whether and from which IP pings arrive.I get no notification on “down”.
No integration channel is assigned, or (for email) the SMTP settings are missing. Set up a channel under “Integrations” and assign it to the check.
Read on: Healthchecks: monitor cron jobs and backups →Stirling-PDF: The page answers with 403 Forbidden.
The lock from step 1 does not let your address through. Usually the IPv6 is missing or has changed – look up both addresses again (see there), correct
Read on: Stirling-PDF: The PDF Toolbox on Your Own Server →sourcerange and restart with docker compose up -d.The page doesn’t load (Traefik 404) even though the container is running.
The health check isn’t
Read on: Stirling-PDF: The PDF Toolbox on Your Own Server →healthy yet – Traefik deliberately doesn’t route then. Wait 20–30 seconds after start; check the status with docker inspect -f '{{.State.Health.Status}}' stirling-stirling-pdf-1. Only once it says healthy does the domain answer.Login with admin/stirling fails.
Either the password was already changed (then use the new one), or the config in the
Read on: Stirling-PDF: The PDF Toolbox on Your Own Server →configs volume is inconsistent. To reset, stop the app and check the user config in the configs folder; if in doubt clear the folder (note: this resets all settings, after which the default credentials apply again).I’m suddenly logged out after the password change.
That’s not a fault: Stirling-PDF discards the session as soon as the password has been set. Just log in again with user
Read on: Stirling-PDF: The PDF Toolbox on Your Own Server →admin and the new password.A newly added OCR language doesn’t show up.
The application reads
Read on: Stirling-PDF: The PDF Toolbox on Your Own Server →/usr/share/tessdata at start. So run docker compose restart after copying the .traineddata – and check that the file really sits in the mounted data folder and ends in .traineddata.Office conversions or OCR are missing entirely.
Then you’re running the
Read on: Stirling-PDF: The PDF Toolbox on Your Own Server →-ultra-lite variant of the image: it lacks LibreOffice and Tesseract, so those tools have no function. Switch to the standard tag (stirlingtools/stirling-pdf:3.2.2) and run docker compose up -d – the price is about 2.5 GB more image.Large files cause errors or long waits.
OCR and conversion are memory-intensive. On a small VPS RAM can run short – then either process smaller files or move to a larger product.
Read on: Stirling-PDF: The PDF Toolbox on Your Own Server →Syncthing: The page answers with 403 Forbidden.
The lock from step 2 does not let your address through. Usually the IPv6 is missing or has changed – look up both addresses again (see there), correct
Read on: Syncthing: sync files between devices without a cloud →sourcerange and restart with docker compose up -d.The container won’t start / restart loop with permission denied.
The permissions on the
Read on: Syncthing: sync files between devices without a cloud →config or data folder are wrong. chown -R 1000:1000 /opt/syncthing/config /opt/syncthing/data and restart (see the warning in step 1).The browser reports an invalid certificate even though the container is running.
The health check isn’t
Read on: Syncthing: sync files between devices without a cloud →healthy yet, so Traefik doesn’t know the domain and answers with its fallback certificate (with curl -k you’d get a 404). Wait up to 60 seconds after start, check docker inspect -f '{{.State.Health.Status}}' syncthing-syncthing-1 and reload the page. If it stays that way, look in docker compose logs for why the health check fails.Two devices won’t connect.
Check three things: is port 22000 (TCP+UDP) open in both firewalls – UFW on the server and, where applicable, the netcup firewall in the SCP? Did you enter the ID on both devices (pairing is mutual)? And is the ID exact (typos are caught easily thanks to a built-in checksum)? A “Disconnected” state with correctly entered IDs almost always points to the firewall port.
Read on: Syncthing: sync files between devices without a cloud →A folder is stuck at “Syncing 0%”.
Usually the share confirmation is missing on the other side, or the folder ID doesn’t match – it must be identical on both devices. Also check the write permissions in the target folder.
Read on: Syncthing: sync files between devices without a cloud →No access after setting the GUI password.
Forgot the password? You can reset it in
Read on: Syncthing: sync files between devices without a cloud →config.xml (<gui> block) by removing the <user> and <password> lines and restarting Syncthing – then the interface is reachable without a login again (and you set it anew immediately).FreshRSS: The page responds with 403 Forbidden.
The lock from step 1 doesn’t let your address through. Usually the IPv6 is missing or has changed – look up both addresses again (see there), correct
Read on: FreshRSS: Your Own RSS Reader →sourcerange and restart with docker compose up -d.After setup you end up back at step 1 of the wizard.
The installation only counts as finished once you click “Complete installation” in the last step – close the browser window before that and the next visit drops you back into the wizard. Just walk through it again and click all the way to the end this time. You don’t have to worry about file permissions along the way: the official image fixes group and mode of the
Read on: FreshRSS: Your Own RSS Reader →data directory on every start – including a folder restored from a backup.Feeds don’t refresh automatically.
First check whether the cron entry inside the container exists at all:
Read on: FreshRSS: Your Own RSS Reader →docker compose exec freshrss crontab -l must print a line starting with your CRON_MIN minutes (13,43 * * * * …). If it’s missing, CRON_MIN wasn’t set at start – add the variable and run docker compose up -d. What the last run did is logged inside the container at /tmp/FreshRSS.log (docker compose exec freshrss tail /tmp/FreshRSS.log). You can trigger a refresh anytime with docker compose exec -u www-data freshrss ./cli/actualize-user.php --user admin.The mobile app won’t connect and reports a server error.
If
Read on: FreshRSS: Your Own RSS Reader →https://YOUR_DOMAIN/api/greader.php answers 503 Service Unavailable!, the server-wide switch from step 6 is missing: without the “Allow API access” box under Administration → Authentication, even a configured API password gets you nowhere. With both in place the API answers a login with 200 and returns an Auth token.A feed from your own network stays empty.
Since 1.30 FreshRSS blocks local targets; the log says
Read on: FreshRSS: Your Own RSS Reader →URL is not allowed to be resolved or Fetching this URL is not allowed, because the host’s IP is not in the allowlist. The fix is the INTERNAL_HOST_ALLOWLIST environment variable (see the box above) – or the same list under Administration → System configuration. If a feed from the public internet stays empty, the URL is usually an HTML page instead of the feed; search the page source for application/rss+xml.Older articles disappear after a while.
That’s archiving, and its defaults are deliberately strict: FreshRSS keeps articles for three months and at most 200 per feed, but never fewer than 50 – favourites and labelled articles are left alone. If you want to scroll back further, raise the values under Settings → Archiving or per feed in its settings; the database grows accordingly.
Read on: FreshRSS: Your Own RSS Reader →systemctl start fails, status shows status=203/EXEC.
systemd couldn’t execute the program from
Read on: Understanding systemd: units, journal & timers →ExecStart; the journal says Unable to locate executable. Either the path is wrong, or the file is missing its executable bit (chmod +x). Without a leading /, systemd only searches /usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin (check with systemd-path search-binaries-default) – so your own script under /opt or /root needs an absolute path.systemd warns “The unit file, source configuration file or drop-ins of … changed on disk”.
You edited a unit file, but systemd doesn’t pick up changes automatically. After every change under
Read on: Understanding systemd: units, journal & timers →/etc/systemd/system/: systemctl daemon-reload.The timer doesn’t show up in list-timers.
It wasn’t enabled.
Read on: Understanding systemd: units, journal & timers →systemctl enable --now SERVICE.timer – and remember the timer triggers the service, so you need both files (.service and .timer).systemctl enable answers “The unit files have no installation config”.
The unit is missing the
Read on: Understanding systemd: units, journal & timers →[Install] section with WantedBy=; in systemctl status you spot it by the static in the Loaded: line. Without [Install] systemd doesn’t know when to start the unit automatically – for timers it needs WantedBy=timers.target.The journal is huge / eats disk.
By default it grows in bounds, but you can trim it:
Read on: Understanding systemd: units, journal & timers →journalctl --vacuum-time=14d deletes entries older than 14 days, journalctl --disk-usage shows the consumption.“Host validation failed” instead of the dashboard.
The most common trap:
Read on: Homepage: a dashboard for your self-hosted services →HOMEPAGE_ALLOWED_HOSTS is missing or has the wrong domain. Enter exactly the domain you access it under, then docker compose up -d.The resource widgets show no or wrong values.
Homepage reads CPU and RAM from within the container (no socket needed). If
Read on: Homepage: a dashboard for your self-hosted services →disk: / shows the container filesystem instead of the host disk, mount the desired path as an additional volume (e.g. - /:/host:ro and disk: /host).An icon doesn’t load.
The name doesn’t match the icon catalog. Write the service name lowercase and without spaces (
Read on: Homepage: a dashboard for your self-hosted services →nextcloud.png), or place a custom image in the icons folder (mounted to /app/public/icons) and reference it as /icons/name.png. Homepage only finds new custom images after docker compose restart; until then the path returns a 404.The container tile shows no status.
The value at
Read on: Homepage: a dashboard for your self-hosted services →container: must be the exact container name. Find it with docker ps --format '{{.Names}}' – with Compose it’s usually folder-service-1 (e.g. traefik-traefik-1).Changes to the YAML files don’t take effect.
If it’s the title or layout from
Read on: Homepage: a dashboard for your self-hosted services →settings.yaml, all that’s usually missing is a click on the refresh icon at the bottom right (see step 8). Otherwise a syntax error often aborts the parsing. YAML is indentation-sensitive – check the logs with docker compose logs homepage for error lines and use consistent spaces (no tabs).You get “Authentication error – Auth is disabled or misconfigured” instead of the sign-in form.
Then
Read on: Homepage: a dashboard for your self-hosted services →HOMEPAGE_AUTH_ENABLED is set but the secret or the password arrives empty in the container – usually because the .env sits in the wrong folder or is missing a line. The log says Password auth is enabled but required settings are missing; docker compose config shows you which values Compose actually substitutes.The container stays unhealthy.
Almost always the IPv6 trap from step 4: the health check queries
Read on: Host your own website with Hugo →localhost but nginx only listens on IPv4. Switch to http://127.0.0.1/. Check with docker inspect --format '{{.State.Health.Status}}' CONTAINER.Traefik shows 404 page not found (instead of your site).
That’s the Traefik 404, not the nginx one – Traefik finds no matching router. Most common causes: the container isn’t
Read on: Host your own website with Hugo →healthy yet, the Host() rule has the wrong domain, or the proxy network isn’t external. See the 502/404 chapter in Understanding Docker networks.All links and images are broken.
The
Read on: Host your own website with Hugo →baseURL in hugo.toml doesn’t match the real domain. Hugo bakes absolute URLs based on this value – fix it and rebuild.A post doesn’t appear.
Check the
Read on: Host your own website with Hugo →date in the front matter: if it’s in the future, Hugo won’t build the post (see the warning box in step 3). A draft: true also hides content in a normal build.module "PaperMod" not found in "/src/themes/PaperMod" during the build.
The theme folder is missing from the build context – usually because it’s a Git submodule that wasn’t copied, or a
Read on: Host your own website with Hugo →.dockerignore excludes it. Store the theme as a real folder as in step 1.Container can’t reach another by name (bad address).
Both aren’t on the same named network, or one uses the default
Read on: Docker networks: bridge, internal DNS & proxy network →bridge (no DNS). Check which networks a container is on with docker inspect -f '{{range $k,$v := .NetworkSettings.Networks}}{{$k}} {{end}}' CONTAINER.Docker networks: Traefik returns 502 Bad Gateway.
Almost always Traefik and the app are on different
Read on: Docker networks: bridge, internal DNS & proxy network →proxy networks because the network was created twice. Make sure external: true is set in Compose and check with docker network inspect proxy whether both containers are listed.network proxy declared as external, but could not be found on up.
The external network doesn’t exist yet. Create it once:
Read on: Docker networks: bridge, internal DNS & proxy network →docker network create --ipv6 --subnet fd00:cafe::/64 proxy. Do not let Traefik create the network itself – it then comes up without IPv6, and behind the proxy IPv6 visitors show up as the gateway address instead of their real IP.Database has internet despite internal.
It’s also attached to a non-internal network (e.g.
Read on: Docker networks: bridge, internal DNS & proxy network →proxy). A container has the sum of the access of all its networks – the DB belongs only on the internal network, never on the proxy network.Two stacks collide on the subnet.
Docker assigns
Read on: Docker networks: bridge, internal DNS & proxy network →172.x ranges automatically, but with many networks the pool can run short (could not find an available, non-overlapping IPv4 address pool). Clean up unused networks: docker network prune.Permission denied even though the permissions look right.
Check the permissions of the parent directory: if it’s missing the
Read on: Understanding Linux Users, Groups & File Permissions →x bit, you can’t reach the file at all, no matter what its own permissions are. ls -ld /path/to/folder shows it.docker ps still says “permission denied” after usermod -aG docker.
The new group isn’t active in the current session yet – log out and back in (see the warning box in step 7).
Read on: Understanding Linux Users, Groups & File Permissions →id in the new session must show docker.New files have unexpected permissions.
That’s set by the
Read on: Understanding Linux Users, Groups & File Permissions →umask – it subtracts permissions from the defaults. On Debian 13 root has 0022 (files 644, directories 755), normal users with their own group have 0002 (664 and 775). Check it with the umask command (no argument).A container won’t write to the volume.
The process inside the container runs under a specific UID (often not root). Set the owner of the host directory to match:
Read on: Understanding Linux Users, Groups & File Permissions →chown -R 1000:1000 ./data – the image’s docs name the correct UID (environment variables like PUID/PGID).usermod dropped the user from groups.
You used
Read on: Understanding Linux Users, Groups & File Permissions →-G without -a. -G replaces the secondary groups. Always use usermod -aG. Repair: re-add the missing groups with usermod -aG group1,group2 user.The search returns nonsense after the model switch.
The photos are still (or partially) indexed with the old model – old and new vectors don’t mix. Start the All run under Job Queues → Smart Search and wait until the queue is empty. Exactly this mixed state also occurs if you save the setting but forget the re-index.
Read on: Optimizing Immich: mobile backup & AI search (Part 2) →With an nllb-… model the search is no better than before.
Immich doesn’t offer the language hint these models expect (see the warning box in step 3). Switch to an
Read on: Optimizing Immich: mobile backup & AI search (Part 2) →XLM-… or SigLIP2 model and re-index.The ML container exits with exit 137 after the model switch.
Out of memory: the new model no longer fits next to the server, the database and your other services. Either pick a smaller model or add RAM – the XLM base model uses around 1 GB for the ML container alone.
Read on: Optimizing Immich: mobile backup & AI search (Part 2) →The external library stays empty after the scan.
Almost always the path is wrong: the import path must be the container path (
Read on: Optimizing Immich: mobile backup & AI search (Part 2) →/mnt/archive), not the host path. Check with docker compose exec immich-server ls /mnt/archive whether the container sees the files at all – if nothing shows up, the volume entry is missing or you skipped docker compose up -d after the change.The phone only backs up while the app is open.
On Android, battery optimization kills the background worker (exempt the app, see step 1); on iOS, Background App Refresh is off or iOS deprioritizes the app – opening it more often genuinely helps. And: by default, backup runs on Wi-Fi only – photos taken on the go are only “missing” until you’re back home.
Read on: Optimizing Immich: mobile backup & AI search (Part 2) →Browser shows NET::ERR_CERT_AUTHORITY_INVALID, curl says self-signed certificate.
The server is serving Traefik’s built-in fallback certificate (
Read on: How HTTPS works and what Traefik does for you →TRAEFIK DEFAULT CERT) because issuance failed. Almost always: the A/AAAA record points to the wrong IP (check with dig YOUR_DOMAIN) or port 80 is closed in the firewall – the HTTP-01 challenge never arrives. The exact cause is in the Traefik logs: docker compose logs traefik | grep -i acme.The issuer carries a (STAGING) prefix, for example (STAGING) Ersatz Emmer YR2.
Let’s Encrypt’s test CA is still active – browsers distrust it on purpose. Remove the staging line from the Traefik configuration, empty
Read on: How HTTPS works and what Traefik does for you →acme.json, restart the container (details in the Traefik tutorial).certificate has expired.
Automatic renewal has been failing for at least 30 days – same list of causes as the first error, just long unnoticed. If the message appears on one device only: check that device’s system clock, TLS is time-sensitive.
Read on: How HTTPS works and what Traefik does for you →Let’s Encrypt reports too many certificates already issued.
Rate limit hit, usually from trial-and-error loops against the production CA. Switch to the staging CA until your setup works – and back up
Read on: How HTTPS works and what Traefik does for you →acme.json instead of re-issuing certificates.unable to get local issuer certificate on an old client.
The system is missing the root certificate from step 3 – its root store is outdated. On Debian:
Read on: How HTTPS works and what Traefik does for you →apt update && apt install ca-certificates.AdGuard Home: The page responds with 403 Forbidden.
The lock from step 2 doesn’t let your address through. Usually the IPv6 is missing or has changed – look up both addresses again (see there), correct
Read on: AdGuard Home: network-wide ad and tracking blocker →sourcerange and restart with docker compose up -d.The container won’t start, the log says “listen udp :53: bind: address already in use”.
systemd-resolved (or another DNS service) occupies port 53. disable the stub listener as in step
1, then docker compose up -d again.docker compose up fails with “cannot assign requested address” for 10.8.0.1.
the WireGuard
interface
Read on: AdGuard Home: network-wide ad and tracking blocker →wg0 with 10.8.0.1 doesn’t exist (yet) – Docker can’t bind the port to a non-existent
address. first set up the WireGuard VPN and bring wg0 up
(ip -br addr show wg0 must show 10.8.0.1), then start the container.After the setup, the web interface is no longer reachable.
in the wizard, the admin port was set
to 80 (the suggestion) instead of 3000 – but Traefik forwards to 3000. in
Read on: AdGuard Home: network-wide ad and tracking blocker →./conf/AdGuardHome.yaml under http: correct the address to 0.0.0.0:3000 and docker compose restart.DNS doesn’t filter, even though the device is connected.
the browser uses DNS-over-HTTPS
(DoH) and thus bypasses your server completely – Firefox and Chrome have this active by default in
part. disable “Secure DNS” / “DNS over HTTPS” in the browser settings. You can check with
Read on: AdGuard Home: network-wide ad and tracking blocker →dig @10.8.0.1 … (always takes effect).A website is suddenly broken (empty pages, missing images, no login).
overblocking – a block
list blocks a domain the site really needs. find the blocked domain in the query log, allow it
via right-click/menu (exception) or disable the overly aggressive list.
Read on: AdGuard Home: network-wide ad and tracking blocker →The runner restarts and reports “cannot ping the docker daemon … certificate is valid for docker, …, not fjr-docker”.
The DinD service is named something other than
Read on: Forgejo Actions: your own CI/CD runner with Docker →docker, but its TLS
certificate is issued for docker. name the DinD service exactly docker (as above) and
address it via DOCKER_HOST: tcp://docker:2376 – then the name matches the certificate.The job starts but fails at actions/checkout with a connection error.
The runner was
registered with an internal instance URL (
Read on: Forgejo Actions: your own CI/CD runner with Docker →http://forgejo:3000). The job containers in DinD
can’t resolve this name. re-register with the public URL https://YOUR_DOMAIN (delete the
.runner file in the volume first, or recreate the volume).The runner doesn’t appear in the overview at all / the registration fails.
Wrong or already-used
token, or the runner can’t reach Forgejo. get a fresh token (step 1) and check that the runner
container reaches
Read on: Forgejo Actions: your own CI/CD runner with Docker →https://YOUR_DOMAIN (docker compose run --rm runner wget -qO- https://YOUR_DOMAIN/api/healthz).A job stays “pending” forever.
No runner has a matching label. The workflow uses
Read on: Forgejo Actions: your own CI/CD runner with Docker →runs-on: docker, so the runner must carry the label docker. check the labels when registering; the runner
overview shows the labels per runner.actions/checkout can’t find the action.
Forgejo loads actions from a configured registry (by
default
Read on: Forgejo Actions: your own CI/CD runner with Docker →data.forgejo.org). If the server is completely cut off from the internet, that fails.
allow outbound HTTPS access or mirror actions in an internal registry.mail-tester shows “reverse DNS does not match”.
The PTR entry is missing, not propagated yet, or
doesn’t match the A record. Set the PTR in the provider panel to
Read on: Email deliverability: SPF, DKIM, DMARC and PTR →mail.YOUR_DOMAIN, check with
dig -x, and make sure the name points forward to the same IP.DKIM fails (DKIM: FAIL or “no signature”).
The DNS record was adopted incorrectly (genuinely
truncated key, wrong selector) or not propagated yet. Copy the value exactly from the mail server
UI, match the selector in the record (
Read on: Email deliverability: SPF, DKIM, DMARC and PTR →SELECTOR._domainkey) with the one configured in the server,
then counter-check with dig. Two quoted blocks are normal there, see step 3.SPF “permerror” or “too many DNS lookups”.
Several SPF records, or too many nested
Read on: Email deliverability: SPF, DKIM, DMARC and PTR →include:
(limit: 10 DNS lookups). Check with dig +short TXT YOUR_DOMAIN | grep spf1 that really
only one line comes back, consolidate to one SPF record and remove unnecessary include:.Mails to Outlook/Hotmail land in spam or get rejected.
A hard rejection with
Read on: Email deliverability: SPF, DKIM, DMARC and PTR →550 5.7.515 Access denied, sending domain … does not meet the required authentication level is
not a reputation problem but Microsoft’s authentication rule from step 7. If the mails only land in
the junk folder, Microsoft is simply strict with new IPs – only the warm-up from step 8 helps there.Your IP is on a block list.
The IP was with a spammer before you, or a mailbox of yours sends
spam. Check on the common block-list checkers, and on a legitimate hit have it removed via the
respective delisting form – and fix the cause (compromised account).
Read on: Email deliverability: SPF, DKIM, DMARC and PTR →The web interface on port 8080 doesn’t respond.
The container is still booting or port 8080 is
occupied/blocked. Check
Read on: Stalwart: a lightweight mail server in one container →docker compose ps, read docker compose logs and make sure the
firewall lets port 8080 (and later 443) through. If the log
output stays completely empty after the setup, the log destination is still set to Log file.
Switch it to Console in the console under Settings → Telemetry → Tracers and restart.The first sign-in fails with “Client metadata documents are disabled”.
You’re opening the setup wizard via HTTPS or your reverse proxy. As long as Stalwart is in bootstrap mode, signing in only works via
Read on: Stalwart: a lightweight mail server in one container →http://…:8080/admin, directly via the IP or through an SSH tunnel to localhost:8080.Signing in fails with “Unknown client id”.
You’re opening the console via
Read on: Stalwart: a lightweight mail server in one container →http://…:8080 or the IP address. After the setup, signing in only works at
https://mail.YOUR_DOMAIN/admin, with the hostname from the wizard and over HTTPS.I missed the bootstrap password.
As long as the wizard isn’t finished, a
Read on: Stalwart: a lightweight mail server in one container →docker compose restart
is enough; Stalwart then logs a new one-time password. More permanently: set a
STALWART_RECOVERY_ADMIN=admin:YOUR_PASSWORD under environment: in the compose.yaml and restart
with docker compose up -d. That gives you a fixed recovery-admin account.No TLS certificate, the HTTPS address shows a warning.
Either Let’s Encrypt can’t reach your
server on port 443 (Stalwart uses the TLS-ALPN-01 challenge over 443), or one of the five hostnames
from step 1 is missing in DNS. The log names the culprit:
Read on: Stalwart: a lightweight mail server in one container →ACME authentication error … NXDOMAIN looking up A for autoconfig.YOUR_DOMAIN. Add the missing
records, open port 443 in the firewall; Stalwart retries the certificate request automatically
afterwards.Mails to the outside stay stuck, logs show timeouts on port 25.
Your provider blocks outbound
SMTP traffic. At netcup the default policy “netcup Mail block” (ports 25/465/587) is to blame: in
the SCP under Firewall → Policies, take that netcup template off the server, no ticket needed,
see netcup firewall setup. Without it, no delivery to other
servers is possible.
Read on: Stalwart: a lightweight mail server in one container →Other servers don’t accept your mails or they land in spam.
Missing or wrong PTR entry, no
SPF/DKIM/DMARC. That’s not a Stalwart error but a matter of DNS/reputation configuration; see the
email deliverability tutorial.
Read on: Stalwart: a lightweight mail server in one container →The page answers with 403 Forbidden
(behind Traefik only). The lock from step 4 does not let your address through. Usually the IPv6 is missing or has changed – look up both addresses again (see there), correct
Read on: Your own mail server with Mailcow: setup from scratch →sourcerange and restart with docker compose up -d.The interface only shows Fatal error: … Failed opening required '/web/inc/app_info.inc.php'.
The generator ran without
Read on: Your own mail server with Mailcow: setup from scratch →umask 0022, for example after a fresh SSH login or on a server whose default umask is stricter (027 after a Lynis hardening, say). The file then gets mode 640, and PHP inside the container can’t read it. chmod 644 data/web/inc/app_info.inc.php brings the page back immediately; the cleaner fix is to delete the folder and repeat step 3 in one session with umask 0022, so no other file is affected.generate_config.sh aborts with Cannot find command 'jq'.
The
Read on: Your own mail server with Mailcow: setup from scratch →jq package is missing. sudo apt install -y jq and start the generator again.The generator reports “User declined to create daemon.json” and aborts.
On hosts with active
IPv6 you answered the question about the IPv6-capable Docker configuration with
Read on: Your own mail server with Mailcow: setup from scratch →n – without it
mailcow won’t run there, and an open relay looms. Create /etc/docker/daemon.json containing
{"ipv6": true} (Docker 28 and newer), restart Docker with sudo systemctl restart docker and run
./generate_config.sh again – or simply confirm the question with Enter on the second attempt, then
the generator does both itself.The webmail only answers Unauthorized.
SOGo doesn’t know your mail domain: it reads the domain
list exclusively at startup and wasn’t restarted after the domain was created – its logs say
Read on: Your own mail server with Mailcow: setup from scratch →No authentication sources defined - nobody will be able to login. Restart SOGo via E-Mail → Restart
SOGo. If that doesn’t help, a failed login is still stuck in the cache: docker compose restart memcached-mailcow sogo-mailcow.No certificate, acme-mailcow keeps restarting
(only without Traefik). Let’s Encrypt can’t reach your server on port
80, or the A record of
Read on: Your own mail server with Mailcow: setup from scratch →mail.YOUR_DOMAIN is wrong. Check with docker compose logs acme-mailcow
whether the hostname and IP match, and that port 80 is open through UFW and the netcup firewall.Mails to the outside aren’t delivered, logs show timeouts on port 25.
Your provider blocks
outbound SMTP traffic (common as spam protection). At netcup it’s the default policy “netcup Mail
block” (ports 25/465/587): in the SCP under Firewall → Policies, take that netcup template off
the server – no support ticket needed, details in
netcup firewall setup. Without it you can’t send mail to
other servers – receiving and local delivery still work.
Read on: Your own mail server with Mailcow: setup from scratch →Ports 80/443 can’t be bound (address already in use).
A web server or reverse proxy (e.g.
Traefik) already runs on the host. Either mailcow gets a server of its own, or you put it behind the
proxy as in step 4. The mail ports sit directly on the host either way.
Read on: Your own mail server with Mailcow: setup from scratch →Behind Traefik the interface doesn’t load, the browser reports too many redirects.
mailcow.conf
still says HTTP_REDIRECT=y. mailcow’s nginx then redirects even the requests Traefik passes on
unencrypted to HTTPS – in a circle. Set HTTP_REDIRECT=n and run docker compose up -d.Behind Traefik, mail programs show a self-signed certificate.
The dumper wrote nothing or didn’t
restart Postfix and Dovecot.
Read on: Your own mail server with Mailcow: setup from scratch →docker compose logs certdumper tells you why: acme.json is not a file means a wrong path to Traefik’s directory. If there is no Restarting container … was successful, the names in --restart-containers are wrong – compare them with
docker compose ps --format '{{.Name}}'.Containers start slowly or are killed by the kernel (OOM).
Too little RAM. Go to at least 6–8 GB
or disable ClamAV in
Read on: Your own mail server with Mailcow: setup from scratch →mailcow.conf (SKIP_CLAMD=y) – the virus scanner is the biggest memory
eater.The app reports “Cannot connect” or the web client stays empty.
The
Read on: ntfy: push notifications to your phone →NTFY_BASE_URL doesn’t
match the called address. It must be exactly your public HTTPS URL (https://ntfy.YOUR_DOMAIN,
without a trailing slash). After a change, run docker compose up -d again.curl returns HTTP 401 or 403.
With
Read on: ntfy: push notifications to your phone →deny-all, missing or wrong credentials are the most
common error. Check the user/password (docker exec ntfy ntfy user list) and, when sending, supply
-u USER:PASSWORD or the bearer token. A 403 means the user exists but has no rights to this
topic – then grant rights with ntfy access.Messages arrive in the browser but not as push on the phone when the tab is closed.
Browser push
needs granted notification rights and an active service worker; that’s unreliable once the tab is
closed. For real “on the go” push, use the ntfy app – it keeps the connection in the background.
Read on: ntfy: push notifications to your phone →502 Bad Gateway from Traefik.
The container isn’t ready yet or listens on the wrong port.
Check
Read on: ntfy: push notifications to your phone →docker compose logs ntfy and that the label loadbalancer.server.port=80 is set – ntfy
listens on port 80 in the container (NTFY_LISTEN_HTTP=":80").429 Too Many Requests with many messages in quick succession.
ntfy limits the rate per sender
by default to prevent abuse. On a private server with your own scripts you rarely hit this – but a
loop script without a pause does. Bundle messages instead of firing them every second, or raise the
limits specifically via the
Read on: ntfy: push notifications to your phone →NTFY_VISITOR_* environment variables (described in the ntfy docs under
“Rate limiting”). NTFY_BEHIND_PROXY: "true" is a prerequisite so the limit applies per real IP
instead of per Traefik container.The container writes, but the bind-mount folder on the host stays empty.
You used a relative
path that points somewhere other than intended, or Docker created the path anew as an empty folder.
With
Read on: Docker volumes vs. bind mounts: where data lives →docker run, always give bind mounts an absolute path (/opt/app/config, not config).
If this host path doesn’t exist yet, Docker silently creates it as an empty folder – so check with
ls that you really hit the right one. In the compose.yaml, on the other hand, ./ paths are
perfectly fine – they’re relative to the compose.yaml and thus unambiguous. Note also: docker run -v config:/data (without / or ./ in front) is not a bind mount, but creates a named volume
called config.Permission denied as soon as the container tries to write into the mount.
The process in the
container runs under a different UID than the owner of the host folder – typical with bind mounts.
With named volumes this rarely happens (Docker sets the permissions). With bind mounts, give the
folder to the matching user (
Read on: Docker volumes vs. bind mounts: where data lives →chown -R 1000:1000 /opt/app/data) or set the UID the container runs
under via the user: key in the compose.yaml.Docker volumes vs. bind mounts: After docker compose down all data is gone.
You used
Read on: Docker volumes vs. bind mounts: where data lives →docker compose down -v – the -v
deletes the named volumes too. For a normal restart, work without -v. Use -v deliberately
only when you really want to start from scratch.docker system prune deleted data.
docker volume prune or docker system prune --volumes
removes volumes that no container is currently attached to. With docker volume prune, named
volumes are protected by default – only anonymous volumes are deleted; named ones only go with
--all/-a. (With docker system prune, on the other hand, -a/--all controls the images, not
the named volumes.) Another strong argument for naming – an sk-demo-vol survives an accidental
docker volume prune, an anonymous volume doesn’t. Still, only run prune with volumes when all
important stacks are active, or remove specifically with docker volume rm.Matomo: The page responds with 403 Forbidden.
The lock from step 3 doesn’t let your address through.
Usually the IPv6 is missing or has changed – look up both addresses again (see there), correct
Read on: Self-hosting Matomo cookieless, without a banner →sourcerange and restart with docker compose up -d.The browser shows a certificate error or 404 page not found.
Traefik hasn’t fetched the Let’s
Encrypt certificate yet, or the DNS record doesn’t point to the server. Check with
Read on: Self-hosting Matomo cookieless, without a banner →dig stats.YOUR_DOMAIN that the IP is correct, and look at the Traefik logs. You find the exact
container name from your Traefik setup with docker ps | grep traefik, then docker logs <container-name> (for us e.g. docker logs traefik-traefik-1). The HTTP challenge fails if port 80
isn’t reachable from outside – check your firewall and the
netcup firewall.The installer reports SQLSTATE... Connection refused or hangs at the database.
MariaDB wasn’t
ready on the first start. Give the DB a moment and reload the page. Check with
Read on: Self-hosting Matomo cookieless, without a banner →docker compose logs db whether it says ready for connections. If an access error appears instead, the DB_PASSWORD
in the .env and the already-created DB no longer match – then a clean restart with docker compose down -v (careful: deletes the data) and docker compose up -d helps.Warning “It looks like the trusted_hosts setting is not correct”.
Matomo checks, for security
reasons, under which hostname it’s called. The warning appears when you change the domain. Confirm
the correct hostname via the button in the message – Matomo then enters it in
Read on: Self-hosting Matomo cookieless, without a banner →config/config.ini.php.No visits appear in the dashboard.
The tracking code is missing, incorrectly embedded, or you’re
visiting your own site (Matomo ignores you if your IP is excluded). Open your website in a private
window and check in the network tab whether a request to
Read on: Self-hosting Matomo cookieless, without a banner →matomo.php goes out. In Matomo,
Administration → Diagnostic → Tracking failures helps.The dashboard loads very slowly.
The on-the-fly archiving computes on every call. Set up the
archiving cron from step 8 and switch report generation to cron.
Read on: Self-hosting Matomo cookieless, without a banner →The container restarts repeatedly (Restarting), the log says bind: address already in use.
Forgejo’s built-in SSH server wants to listen on port 22, which the bundled OpenSSH service inside the container already occupies. Set
Read on: Forgejo: your own Git server behind Traefik →SSH_PORT and SSH_LISTEN_PORT both to the same value (here 2222) – then Forgejo starts cleanly.The container takes forever to become healthy.
By default, Docker runs the first healthcheck only after the
Read on: Forgejo: your own Git server behind Traefik →interval (30 s) – so the container looks “unhealthy” for 30 s+, even though Forgejo has long been ready in ~2 s. The solution is already in the Compose above: start_interval: 2s checks every 2 seconds during the startup phase and switches to healthy as soon as the app responds. (Requires Docker 25+ / Compose v2.20+ – given on Debian 13.)Forgejo: Traefik returns 502 Bad Gateway.
Almost always the wrong port: Forgejo’s web interface listens internally on 3000, so
Read on: Forgejo: your own Git server behind Traefik →loadbalancer.server.port=3000 must be set and the container must be on the proxy network.Clone links show localhost or the wrong port.
Then
Read on: Forgejo: your own Git server behind Traefik →ROOT_URL, SSH_DOMAIN or SSH_PORT are wrong. Correct the values in the Compose and restart with docker compose up -d.SSH clone fails with Permission denied (publickey).
The SSH server is running, but your public key isn’t stored in the account yet (step 6) – or you forgot the port
Read on: Forgejo: your own Git server behind Traefik →2222.HitKeep: The page responds with 403 Forbidden.
The lock from step 2 doesn’t let your address
through. Usually the IPv6 is missing or has changed – look up both addresses again (see there),
correct
Read on: HitKeep: self-host privacy-friendly web analytics →sourcerange and restart with docker compose up -d.The live verifier stays on “Waiting” / no hits in the dashboard.
Check in the browser (dev tools → Network) whether
Read on: HitKeep: self-host privacy-friendly web analytics →hk.js is loaded at all and the send request
afterwards comes back with status 2xx. Most common causes: the snippet isn’t in the HTML, the
site domain created in HitKeep doesn’t match the hostname of the visited page, or an ad/tracking
blocker filters the call. Since you host under your own domain (first-party), most blockers
don’t apply – but some lists know the path hk.js.All visitors seemingly come from a single IP, country and provider show “(Unknown)”.
Then
Read on: HitKeep: self-host privacy-friendly web analytics →HITKEEP_TRUSTED_PROXIES isn’t taking effect: the range you gave doesn’t contain your
proxy’s IP, and HitKeep only evaluates Traefik’s container IP. Check which subnet the proxy sits
in with docker network inspect proxy – 172.16.0.0/12 covers the usual Docker networks – and
restart the stack (docker compose up -d). After that the real client IP from the
X-Forwarded-For header counts again.Traefik returns 404 or 502.
A
Read on: HitKeep: self-host privacy-friendly web analytics →404 usually means the router rule isn’t matching – check that Host(...) contains your real
domain and the container is on the proxy network. A 502 indicates the wrong port: HitKeep
listens internally on 8080, so loadbalancer.server.port=8080 must be set.After login you land on the login page again (login loop).
That’s almost always a mismatch in
Read on: HitKeep: self-host privacy-friendly web analytics →HITKEEP_PUBLIC_URL: the value must match exactly the address
through which you call HitKeep (including https://, without a trailing slash). Correct the
variable and restart the container.The container won’t start or isn’t healthy.
Look at the logs:
Read on: HitKeep: self-host privacy-friendly web analytics →docker compose logs -f hitkeep. A missing or empty HITKEEP_JWT_SECRET is a
typical start blocker – generate one as in step 1 and enter it.A latest handshake never appears in wg show.
The UDP port isn’t reachable or the
keys don’t match. WireGuard is silent with wrong keys – there’s no error message,
just no handshake. Check:
Read on: WireGuard VPN: secure access to your own server →sudo ufw status (port 51820/udp open?), the netcup firewall
(inbound UDP 51820), the Endpoint in the client (correct public IP?) and that the
private and public keys aren’t swapped.Handshake is there, but no internet arrives in the full tunnel.
Almost always the
routing/NAT. Is
Read on: WireGuard VPN: secure access to your own server →net.ipv4.ip_forward=1 set (sysctl net.ipv4.ip_forward)? If Docker is
running – or UFW is active – the FORWARD DROP trap from the warning box above applies; the
most common mistake then is a missing RELATED,ESTABLISHED rule, i.e. a blocked return path.
Check with sudo iptables -S FORWARD that both PostUp rules really are in the chain. Is the
external interface in the MASQUERADE correct (eth0 vs. something else)?Full tunnel is up, but curl -s ifconfig.me shows your own address.
If it is an IPv6
address,
Read on: WireGuard VPN: secure access to your own server →::/0 is missing from the client’s AllowedIPs – IPv6 then bypasses the tunnel (IPv6
leak). Add it, restart the tunnel and check with curl -4 and curl -6 separately.Full tunnel is up, but DNS queries still run past the tunnel (DNS leak).
Without a
Read on: WireGuard VPN: secure access to your own server →DNS = line, your device keeps querying the DNS servers of your local network – on open
Wi-Fi the operator still sees which domains you visit. On Linux, check with resolvectl status which DNS server is assigned to the wg0 interface, or run a leak test (e.g. on
dnsleaktest.com): if foreign resolvers appear there, enter a real resolver in the
client config (DNS = 1.1.1.1) – or the server itself (10.8.0.1) if a dedicated DNS
resolver runs there.The tunnel is up, but large transfers (SSH, HTTPS, downloads) hang or break off.
An
MTU problem.
Read on: WireGuard VPN: secure access to your own server →wg-quick sets the MTU to 1420; in some networks (DS-Lite, certain mobile
networks) that’s still too high. Try MTU = 1412 or 1280 in the [Interface] section
of the client.wg-quick up reports resolvconf: command not found.
The
Read on: WireGuard VPN: secure access to your own server →DNS = line needs
resolvconf. Either install sudo apt install openresolv or remove the DNS line if
you don’t need the VPN DNS.The connection falls asleep as soon as the phone briefly sends nothing.
The client
sits behind NAT/CGNAT.
Read on: WireGuard VPN: secure access to your own server →PersistentKeepalive = 25 in the client config keeps the
connection open.Your figures are well below ours, especially for the CPU.
A VPS shares the physical
CPU. Check the steal time (
Read on: netcup VPS 1000 G12 benchmarked: how fast is it really? →vmstat 1, column st) and top (line %st). If it’s
persistently high, neighbors on the same host are computing right now. Measure again at a
different time of day, often the difference is gone then.The disk figures are absurdly high (e.g. “10 GB/s random read”).
There are two causes and
you have to rule out both. Either
Read on: netcup VPS 1000 G12 benchmarked: how fast is it really? →--direct=1 is missing, in which case fio measures the
page cache in RAM instead of the NVMe. Or you’re measuring in /tmp. On Debian 13 that’s a
tmpfs and lives entirely in RAM, against which --direct=1 is powerless either; this mistake
showed us 913,000 instead of 101,000 IOPS, almost nine times as much. Check with
findmnt --target . -no FSTYPE what you’re measuring on: if it says tmpfs instead of ext4,
switch to a directory on the real disk such as /var/tmp.lsblk shows ROTA=1 (“rotational”) for vda in the column – is that a hard disk
instead of NVMe?
No. That’s a virtualization artifact: the virtio driver reports the
virtual disk as rotational across the board. The measured 100k+ IOPS and 4 GB/s prove that
real flash storage is behind it.
Read on: netcup VPS 1000 G12 benchmarked: how fast is it really? →The download is much slower than 2 Gbit/s.
Measure against a nearby, fast server
(e.g. Falkenstein). A distant target or a slow counterpart limits the measurement, not your
VPS. A single
Read on: netcup VPS 1000 G12 benchmarked: how fast is it really? →curl stream also doesn’t always exhaust the full bandwidth.Every run delivers different numbers.
Normal, benchmarks fluctuate. Measure multiple
times, discard the first run as a warm-up run and take the median of the rest. For us that
very first run was off by a factor of three on the write test. Also compare only the same
tool versions and parameters with each other.
Read on: netcup VPS 1000 G12 benchmarked: how fast is it really? →docker compose pull pulls no new image, even though a new version exists.
Your tag
points to a fixed version (
Read on: Keeping your whole Docker stack safely up to date →:1.37.2) or to a major tag (:18), under which there’d only be
a new major. pull only fetches what the same tag now points to. For a version jump
you have to bump the tag in the compose.yaml yourself.The app no longer starts after the update or throws database errors.
Usually a breaking
change or a failed migration. Check
Read on: Keeping your whole Docker stack safely up to date →docker compose logs, compare with the release notes.
Set the tag back to the old version and up -d; if the new version already migrated the
data, restore the backup from step 3.Diun reports nothing, even though updates exist.
Check that the containers carry the
label
Read on: Keeping your whole Docker stack safely up to date →diun.enable=true and Diun can read the socket (DIUN_PROVIDERS_DOCKER=true, socket
mounted). For newer version tags the container additionally needs diun.watch_repo=true
– without it, Diun only sees changes to the exactly pinned tag. And: whatever Diun sees for the
first time is only written to the database, not reported (watch.firstCheckNotif is
false) – to test the notification path, set DIUN_WATCH_FIRSTCHECKNOTIF=true once.The disk fills up, even though you regularly run docker image prune.
docker image prune only clears dangling images, not the old tagged versions. Remove them
specifically with docker rmi <image>:<tag> or – with care – docker image prune -a. The
build cache (docker builder prune) can grow too.On pulling you get toomanyrequests / a Docker Hub rate limit.
diun.watch_repo=true
on many images queries many tags. Set the watch interval less often (e.g. once daily) and
narrow with diun.include_tags to relevant versions instead of scanning the whole repo.A freshly set ban doesn’t take effect, the IP keeps getting 200.
Wait up to a minute –
the bouncer only fetches new decisions after the pull interval (step 4).
Read on: CrowdSec: modern, collaborative intrusion prevention →cscli metrics show acquisition shows no line for the log file.
CrowdSec isn’t reading the
logs. Most common cause: the container started before the
Read on: CrowdSec: modern, collaborative intrusion prevention →access.log existed
(No matching files for pattern … in docker logs crowdsec, see step 1) –
cd ~/crowdsec && docker compose restart fixes it. Otherwise check that Traefik really writes to
/var/log/traefik/access.log, that both containers mount the same host path, and that the
acquis.yaml names exactly this path.After restarting Traefik every app returns 403 – including for you.
The bouncer can’t
reach the LAPI; the Traefik log says
Read on: CrowdSec: modern, collaborative intrusion prevention →crowdsecQuery:unreachable with the URL
http://crowdsec:8080/v1/decisions/stream. Check with docker ps that the crowdsec container is
Up – as soon as the next pull succeeds, requests go through again on their own (background in
the box in step 3).CrowdSec bans lots of harmless or no real visitors – the detected IP is always your CDN’s.
If a
CDN like Cloudflare sits in front of Traefik, Traefik only sees its IP. Then have the real
client IP read from the
Read on: CrowdSec: modern, collaborative intrusion prevention →X-Forwarded-For header: fill forwardedHeadersTrustedIPs in the
middleware with the CDN networks – otherwise you end up banning the CDN. Directly at netcup (without
a CDN) there’s nothing to do here.docker compose up -d on Traefik reports a plugin error.
Traefik downloads the plugin from the
net on startup. Check that the server may go out (the netcup
firewall only blocks SMTP outbound, UFW nothing) and that
Read on: CrowdSec: modern, collaborative intrusion prevention →modulename and version are exactly right.CrowdSec bans nothing even though the attacks are in access.log – or it bans 172.18.0.1.
Then Traefik never sees the real source address in the first place. This happens with IPv6 visitors when the
Read on: CrowdSec: modern, collaborative intrusion prevention →proxy network was created without IPv6: Docker then replaces the source address with the bridge gateway’s, every IPv6 request carries the same 172.x.x.x in access.log, and a ban on that either hits nobody or everybody. Recreate the network with --ipv6; the instructions are in Reverse proxy with Traefik.dd overwrote the wrong disk – data gone.
dd doesn’t ask and isn’t mockingly called
“disk destroyer” for nothing. Check the target (of=) always beforehand with lsblk,
and never confuse sda with sdb. There’s no undo – when in doubt, read it three times.kill -9 ended a service, but the database is corrupted afterwards.
-9 gives the
process no chance to close cleanly. Always first use kill without -9 and give the
process a few seconds. Only when it really hangs does the hard variant follow.rsync copied (or deleted) much more than expected.
The trailing slash decides:
Read on: The essential terminal commands for your server →rsync -a /source/ copies the contents of source, rsync -a /source copies the
folder along with it. And --delete deletes everything in the target that’s missing in
the source. Test with -n first, always.A tool reports “command not found”.
The package isn’t installed. Install it (see tip
box above) or check the name. Some tools like
Read on: The essential terminal commands for your server →iotop additionally need sudo to see any
data at all.After tmux, on the next login “everything is gone”.
You started a new session
instead of attaching.
Read on: The essential terminal commands for your server →tmux ls lists running sessions, tmux attach -t 0 attaches you to
the first. Just tmux on its own creates a fresh one every time.A target is at up = 0 or “DOWN” in Prometheus.
Prometheus can’t reach the exporter. For
Read on: Monitoring with Grafana & Prometheus: live dashboards →cadvisor, check that it’s on the same monitoring network and the name and port are exactly
right (cadvisor:8080). For the node job, check the extra_hosts entry on the Prometheus
service and the target host.docker.internal:9100 – without both, Prometheus doesn’t find the
node-exporter in the host network. After changes to the prometheus.yml, restart the
Prometheus container: docker compose restart prometheus.The cAdvisor dashboard partly shows “No data” or cAdvisor won’t start.
If the mounts or
Read on: Monitoring with Grafana & Prometheus: live dashboards →privileged: true are missing, cAdvisor doesn’t see the containers. Check the cadvisor block
(mounts, devices: /dev/kmsg). Individual “No data” panels are normal – some metrics (like CPU
throttling) only exist if you’ve set CPU limits on the containers.Grafana doesn’t load correctly behind Traefik – login fails or the layout is broken.
Almost
always
Read on: Monitoring with Grafana & Prometheus: live dashboards →GF_SERVER_ROOT_URL is wrong. It must be exactly the public address
(https://grafana.YOUR_DOMAIN). Also check that the Traefik label
loadbalancer.server.port=3000 is set – Grafana listens on 3000 internally.Grafana shows “No data” in the panels, even though the targets are up.
Usually the time
range. A fresh stack has no history yet – set “Last 15 minutes” at the top right and wait a few
minutes for data to accumulate. Also check that the Prometheus data source was selected on
dashboard import.
Read on: Monitoring with Grafana & Prometheus: live dashboards →Prometheus won’t start and its log says permission denied for prometheus.yml.
The server is
hardened (
Read on: Monitoring with Grafana & Prometheus: live dashboards →UMASK 027) and Prometheus isn’t allowed to read its configuration. Fix it with
chmod 644 prometheus/prometheus.yml from step 3 and docker compose restart prometheus. If the
data source is missing in Grafana, the same applies to datasource.yml.The disk space on the server grows steadily.
That’s the Prometheus TSDB. Reduce
Read on: Monitoring with Grafana & Prometheus: live dashboards →--storage.tsdb.retention.time (e.g. to 15d) or monitor fewer targets. The prom_data
volume grows with the number of metrics × retention time.Jellyfin: The page answers with 403 Forbidden.
The restriction from step 4 doesn’t let your
address through. Usually the IPv6 is missing or has changed – look up both addresses
again (see there), correct
Read on: Self-hosting Jellyfin: your own media server →sourcerange and restart with docker compose up -d.502 Bad Gateway on access, even though the container is running.
Traefik reaches the
container but hits the wrong port. Jellyfin listens on 8096 – check the label
Read on: Self-hosting Jellyfin: your own media server →traefik.http.services.jellyfin.loadbalancer.server.port=8096 for typos. If a
504 Gateway Timeout comes back after a few seconds instead, the port isn’t the
problem, the network is: then networks: [proxy] is missing and Traefik is running against
an address it can’t reach at all.The libraries stay empty, even though files are there.
Almost always a permission
problem. The container runs as
Read on: Self-hosting Jellyfin: your own media server →1000:1000 (step 4), so the media must belong to that
user: sudo chown -R 1000:1000 /mnt/media. And: in Jellyfin the container path must be
entered (/media/filme), not the host path. Afterwards click “Scan All Libraries” at the
top of the Dashboard – under Scheduled Tasks the same job is called “Scan Media
Library”.Video stutters/buffers, docker stats shows Jellyfin at ~100% CPU.
It’s
transcoding. Under Dashboard → Playback the activity monitor shows whether it says
“Transcode” instead of “Direct Play”. Set the client quality to original, change exotic
codecs to a widely supported format, or give the server more (dedicated) cores.
Read on: Self-hosting Jellyfin: your own media server →After a reboot the library is gone and Jellyfin shows empty folders.
The block storage
wasn’t mounted – usually a missing or wrong
Read on: Self-hosting Jellyfin: your own media server →fstab entry (step 2). Check with df -h /mnt/media and sudo mount -a. The line must use the UUID, not /dev/vdb1.The login page loads, but the app can’t find the server / links point to an internal address.
JELLYFIN_PublishedServerUrl is missing or wrong. Set it in the compose.yaml
to https://jellyfin.YOUR_DOMAIN and restart with docker compose up -d (a restart isn’t
enough for the environment change to take effect).Immich: The page answers with 403 Forbidden.
The restriction from step 3 doesn’t let your
address through. Usually the IPv6 is missing or has changed – look up both addresses
again (see there), correct
Read on: Self-hosting Immich: your private photo backup →sourcerange and restart with docker compose up -d.Uploads of large videos abort after about a minute (error 502 or 499).
Traefik’s
Read on: Self-hosting Immich: your private photo backup →readTimeout (default 60 s) kicks in. Set it to 600s (or higher) as in step 4 and restart
Traefik. This is by far the most common Immich-behind-proxy error.The immich-machine-learning container crashes or exits with “exit 137”, search and face
recognition don’t work.
Too little RAM – the container was killed by the system (out of
memory). Give the server more memory, or disable ML by removing the service
Read on: Self-hosting Immich: your private photo backup →immich-machine-learning from the compose.yaml. Immich then runs without face recognition
and smart search, but upload and timeline work normally.After an update the containers no longer start or report migration errors.
Server, machine
learning and database must run on the same version. Set the new
Read on: Self-hosting Immich: your private photo backup →IMMICH_VERSION in the
.env and update all containers together (docker compose pull && docker compose up -d).
A downgrade after a migration isn’t possible – only a reset from the backup.Immich shows “maintenance mode” / “temporarily unavailable”.
Immich v3 starts into a
maintenance mode under certain database states. The log (
Read on: Self-hosting Immich: your private photo backup →docker compose logs immich-server)
then contains a URL with a one-time token (…/maintenance?token=…) – through it you log
into the maintenance mode and choose “restart” or end it. After that the normal interface is
back.Container won’t start, “permission denied” on the database or upload directory.
UPLOAD_LOCATION or DB_DATA_LOCATION have the wrong access rights or are on a network
drive. Put both on a local disk and make sure Docker may write into them.On login, “Forbidden (403)” or “CSRF verification failed” appears.
PAPERLESS_URL is not
set or set wrong. It must exactly match your HTTPS address (https://paperless.YOUR_DOMAIN,
without a trailing slash). After the correction, docker compose up -d.Files in the consume folder aren’t processed, “permission denied”.
Most common cause: the
folders weren’t created beforehand (step 3), but generated by the Docker daemon on the first
start – then they belong to
Read on: Self-hosting Paperless-ngx: the paperless office →root. With sudo chown -R $(id -u):$(id -g) ~/paperless/consume ~/paperless/export they belong to you again. Otherwise: USERMAP_UID/USERMAP_GID don’t
match the folder’s owner – determine your ID with id -u and id -g, enter the values and
restart.Uploaded documents get stuck “in processing”.
The background processing runs via the
broker. Check that the
Read on: Self-hosting Paperless-ngx: the paperless office →broker container is running, and look under Tasks for the error
message of the failed task. If the broker keeps showing Restarting and its log says
Can't handle RDB format version 15, you attached a Redis volume to Valkey – see “Still
running Redis?” under maintenance.Text recognition returns gibberish or recognizes nothing.
Wrong OCR language. Set
Read on: Self-hosting Paperless-ngx: the paperless office →PAPERLESS_OCR_LANGUAGE=eng (or eng+deu for mixed documents). Only installed languages
work.Office documents (Word, Excel) aren’t accepted or end in a timeout.
Gotenberg and Tika
are responsible for those. Check that both containers are running and
Read on: Self-hosting Paperless-ngx: the paperless office →PAPERLESS_TIKA_ENABLED=1 plus the two endpoint variables are set.During bulk import the server gets very slow, the CPU is constantly maxed out.
OCR is
compute-intensive, and Paperless uses all cores by default. On small servers you can throttle
the load by limiting the number of workers or threads (
Read on: Self-hosting Paperless-ngx: the paperless office →PAPERLESS_TASK_WORKERS,
PAPERLESS_THREADS_PER_WORKER). Then the import takes longer, but the interface stays
usable.After the Traefik restart, the HSTS header doesn’t appear in the curl output.
Usually
the middleware isn’t on the router. Check that the line
Read on: Hardening & optimizing Nextcloud (Part 2) →traefik.http.routers.nc.middlewares
names both middlewares (nc-dav,nc-secure) and that the two nc-secure header labels
are in the nc-app block. Then docker compose up -d nc-app. Traefik only picks up changed
labels when recreating the container.The email test fails (“There was a problem sending the email”).
Almost always
port/encryption or authentication. Combine
Read on: Hardening & optimizing Nextcloud (Part 2) →SSL/TLS with port 465 or None / STARTTLS with
port 587, not crosswise. If your provider uses 2FA, you need an app password (see step 4).
Details are in the Nextcloud log: docker exec -u www-data nc-app php occ log:tail 20.You can’t get in yourself after enforcing 2FA.
You hadn’t set up a second factor yet. Lift
the requirement via the command line, set up your factor calmly and arm it again afterwards:
Read on: Hardening & optimizing Nextcloud (Part 2) →docker exec -u www-data nc-app php occ twofactorauth:enforce --off.In the brute-force box a 172.x.x.x address appears instead of your real IP.
TRUSTED_PROXIES doesn’t match the actual proxy subnets. Print both of them – the
network has an IPv6 and an IPv4 range – and enter them space-separated in the nc-app
environment (part 1, step 2):
docker network inspect proxy -f '{{ range .IPAM.Config }}{{ .Subnet }} {{ end }}'.
Otherwise the brute-force protection bans the proxy in an emergency and thus all users.After a reboot, Nextcloud reports “Redis went away” or gets very slow.
The app container
started before Redis. Make sure
Read on: Hardening & optimizing Nextcloud (Part 2) →nc-redis is in depends_on (part 1) and runs with restart: unless-stopped – then Docker catches the start-order case itself.Nextcloud: The page answers with 403 Forbidden.
The restriction from step 3 doesn’t let your
address through. Usually the IPv6 is missing or has changed – look up both addresses
again (see there), correct
Read on: Self-hosting Nextcloud: your own cloud behind Traefik →sourcerange and restart with docker compose up -d.“Access through untrusted domain” instead of the login page.
Your domain isn’t in
Read on: Self-hosting Nextcloud: your own cloud behind Traefik →trusted_domains. Check NEXTCLOUD_TRUSTED_DOMAINS in the Compose file. To set it
afterwards, use occ: docker exec -u www-data nc-app php occ config:system:set trusted_domains 1 --value=cloud.YOUR_DOMAIN.The security check reports “Your web server is not set up properly to resolve .well-known/caldav”.
The CalDAV/CardDAV redirect isn’t working. Check the
Read on: Self-hosting Nextcloud: your own cloud behind Traefik →nc-dav
middleware labels (step 3) and that the router includes them via
...routers.nc.middlewares=nc-dav. The regex must match the full https://… URL –
redirectregex checks the complete URL, not just the path.Warning “The ‘Strict-Transport-Security’ HTTP header is not set”.
The HSTS header is
missing. Set it as a Traefik middleware and attach it to the router:
Read on: Self-hosting Nextcloud: your own cloud behind Traefik →traefik.http.middlewares.nc-secure.headers.stsSeconds=15552000. Attach it additionally to
the nc-dav middleware on the router (...routers.nc.middlewares=nc-dav,nc-secure). The
header must come from the proxy, not from Nextcloud. In part
2 we set up exactly this nc-secure middleware
fully (including includeSubdomains).Large uploads break off or end with a timeout / “413”.
The PHP limit is too small.
Increase
Read on: Self-hosting Nextcloud: your own cloud behind Traefik →PHP_UPLOAD_LIMIT and PHP_MEMORY_LIMIT (step 3) and restart the container. In
rare cases these variables don’t take effect – then mount your own php.ini snippet into the
image.On the first start the installation aborts with “MySQL server has gone away” or “Connection refused”.
The app container was faster than the database. That’s exactly what the
Read on: Self-hosting Nextcloud: your own cloud behind Traefik →healthcheck with depends_on: condition: service_healthy is for – check that both are
present in your Compose file, and restart with docker compose up -d.Uptime Kuma: The page responds with 403 Forbidden.
The lock from step 1 doesn’t let your address
through. Usually the IPv6 is missing or has changed – look up both addresses again (see
there), correct
Read on: Uptime Kuma: server monitoring behind Traefik →sourcerange and restart with docker compose up -d.Bad Gateway (502) when opening status.YOUR_DOMAIN.
Almost always the port label
Read on: Uptime Kuma: server monitoring behind Traefik →traefik.http.services.kuma.loadbalancer.server.port=3001 is missing or has a wrong port.
Traefik then reaches the container but knocks on the wrong port. Check the label and run
docker compose up -d again.404 page not found instead of Kuma.
As with every app behind Traefik:
Read on: Uptime Kuma: server monitoring behind Traefik →traefik.enable=true set? Container on the proxy network? Is the domain in the Host(...)
rule correct and does the DNS record status.YOUR_DOMAIN point to the server? The Traefik
dashboard shows under “HTTP Routers” whether kuma is registered.The interface loads, but the live update stutters / breaks off.
Kuma uses WebSockets.
Traefik forwards those correctly by default – if the problem still occurs, it’s usually an
upstream CDN/proxy (e.g. Cloudflare in “proxy” mode) that blocks WebSockets. For direct
operation behind Traefik, no extra configuration is needed.
Read on: Uptime Kuma: server monitoring behind Traefik →After a re-setup all monitors are gone.
The
Read on: Uptime Kuma: server monitoring behind Traefik →kuma-data volume was deleted (e.g. by
docker compose down -v). All configuration and history lives solely in this volume – that’s
why it’s at the top of the next section.The container exits again immediately, the log says No persistent volume!.
The
Read on: Vaultwarden: your own password manager behind Traefik →volumes: mapping is missing. Vaultwarden then aborts with the box “It looks like you did
not configure a persistent volume!” and exits with code 1, so your passwords don’t end up
in an ephemeral container. Add ./vw-data:/data as in step 2 and restart.The web interface shows “You need to enable HTTPS!” or the login fails with crypto errors.
Vaultwarden uses the browser’s Web Crypto API, which is only available in a
secure context (real HTTPS). You opened the page over
Read on: Vaultwarden: your own password manager behind Traefik →http:// or with an invalid
certificate. Make sure Traefik fetched a valid Let’s Encrypt certificate (check the Traefik
log) and that you reach the page over https://. The DOMAIN variable must also start with
https://.The admin panel rejects your password, even though it’s correct.
Probably the dollar
signs in the
Read on: Vaultwarden: your own password manager behind Traefik →ADMIN_TOKEN aren’t doubled. In the compose.yaml every $ must become $$.
Check with docker compose exec vaultwarden printenv ADMIN_TOKEN how the token really
arrives inside the container – there it has to be a single $ again. (docker compose config won’t help: it shows the file with the doubled $$.) Also remember: at login you
enter the password, not the hash.The phone app can’t find the server or reports “Server URL invalid”.
The server URL must
be the full
Read on: Vaultwarden: your own password manager behind Traefik →https:// address without a trailing path (https://vault.YOUR_DOMAIN). Also
check whether the domain is reachable from outside via a browser and the certificate is
valid – apps are stricter about certificate errors than browsers.Despite SIGNUPS_ALLOWED=false, someone was able to register.
The setting was probably
set in the admin panel and overrides the environment variable, or the container wasn’t
restarted after the change. Check the value under Settings → General settings in the
panel and restart with
Read on: Vaultwarden: your own password manager behind Traefik →docker compose up -d.The dry run reports No packages found that can be upgraded unattended.
Usually
perfectly normal – no security update is currently pending. Check the configuration
anyway via the
Read on: Automatic security updates with unattended-upgrades →Allowed origins are: line in the --debug run. If no security origins
appear there, the Origins-Pattern from step 3 isn’t right.Updates come, but the server never reboots despite a kernel update.
Usually
Read on: Automatic security updates with unattended-upgrades →Automatic-Reboot is set to "false" (default) – then set it to "true" and give it an
Automatic-Reboot-Time (step 3). If the option is right, check the marker file: without
/var/run/reboot-required the reboot never triggers. The package’s kernel hook is what
sets it – dpkg -S /etc/kernel/postinst.d/unattended-upgrades must report it (step 3)./boot fills up, updates fail.
Old kernels pile up. Set
Read on: Automatic security updates with unattended-upgrades →Remove-Unused-Kernel-Packages "true" (step 3); clean up once with sudo apt autoremove --purge.A package is stubbornly held back (kept back).
unattended-upgrades doesn’t
install updates that would remove other packages. You resolve such cases deliberately
by hand with
Read on: Automatic security updates with unattended-upgrades →sudo apt upgrade and check what happens.You locked yourself out.
ignoreip was missing or contained the wrong IP. Connect
via the console in the netcup SCP (independent of SSH) and unban yourself with
sudo fail2ban-client set sshd unbanip YOUR_OWN_IP. Then enter your IP in ignoreip
and reload. That’s why the whitelist comes first in step 2.fail2ban.service won’t start (systemctl status shows “failed”).
Almost always
a typo in
Read on: Fail2ban: block brute-force attacks automatically →jail.local. Check the syntax with sudo fail2ban-client -t (test mode) –
the command names the faulty line.Your values from jail.local don’t take effect.
Bans only last 10 minutes, or your
own IP gets thrown out despite
Read on: Fail2ban: block brute-force attacks automatically →ignoreip. Almost always the reload is missing – the
service was already running before you wrote your first own line, and start/enable --now does nothing on a running service. What actually applies is shown by
sudo fail2ban-client get sshd bantime (600 = Debian default, 3600 = your hour) and
sudo fail2ban-client get sshd ignoreip; it is applied with
sudo systemctl reload fail2ban.No one is ever banned, even though the log is full of failed attempts.
Check with
Read on: Fail2ban: block brute-force attacks automatically →sudo fail2ban-client status sshd whether Total failed rises at all. If it stays at
0, the filter isn’t finding the entries – usually because an outdated guide set a
logpath to a non-existent file. On Debian 13, remove the logpath from
jail.local and use the journal (step 2).Bans “don’t work” – the IP keeps connecting.
On Debian 13, Fail2ban bans via
nftables (
Read on: Fail2ban: block brute-force attacks automatically →banaction = nftables from defaults-debian.conf). You can see it with
sudo nft list table inet f2b-table: it holds the chain f2b-chain and inside it an
address set addr-set-sshd with the banned IPs. sudo iptables -L -n | grep f2b, on the
other hand, returns nothing – that’s not a fault but the wrong tool layer, where
older guides get stuck. If the table is missing entirely, the interplay with the firewall
is stuck – restart the service and look at /var/log/fail2ban.log.subprocess ssh: Host key verification failed with the SFTP target.
Restic can’t
confirm the SSH host key of the backup server because it isn’t known yet. Connect
once manually (
Read on: Restic backups: encrypted and off-site →ssh BACKUP_USER@YOUR_BACKUP_HOST) and confirm the fingerprint – or
store it with ssh-keyscan YOUR_BACKUP_HOST >> ~/.ssh/known_hosts. After that Restic
runs through.wrong password or repository does not exist.
RESTIC_REPOSITORY or
RESTIC_PASSWORD_FILE isn’t set or points nowhere – so check the EnvironmentFile in
the systemd service. A manually set export only applies in the current shell.repository is already locked.
An aborted run left a lock. Check that really
no backup is running anymore, then
Read on: Restic backups: encrypted and off-site →restic unlock. Never unlock blindly while a run
is active in parallel.The backup gets huge / backs up nonsense.
Restrict it with
Read on: Restic backups: encrypted and off-site →--exclude/--exclude-file (caches, logs, temporary files) and use
--one-file-system so Restic doesn’t dive into mounted foreign filesystems.prune takes forever or was aborted.
No reason to panic –
Read on: Restic backups: encrypted and off-site →prune is resumable and
the repository stays valid. Start it again and afterwards run restic check once.
Separate --prune from the daily backup on large repos (see step 6).The timer runs, but a success message never arrives in Uptime Kuma.
Look at the
last run with
Read on: Restic backups: encrypted and off-site →journalctl -u restic-backup.service. Usually the script aborts
before the curl call (e.g. the DB dump failed) – thanks to set -euo pipefail it
then stops cleanly instead of reporting a broken backup as success. So the missing push
isn’t a bug, but exactly the alarm signal you want.“Certificate invalid” in the browser, or the Traefik log shows ACME errors.
The
three usual reasons: (1) The DNS record doesn’t point to the server yet – check
Read on: Setting up Traefik: reverse proxy with automatic HTTPS →dig +short YOUR_DOMAIN. (2) Port 80 isn’t reachable from outside (firewall/netcup
firewall) – the HTTP challenge needs it. (3) You hit the rate limit of the
production CA – switch to the staging server (tip in step 3), test, then go back.404 page not found when calling the app domain.
Traefik doesn’t know the route.
Check: Does the container have
Read on: Setting up Traefik: reverse proxy with automatic HTTPS →traefik.enable=true? Is it on the proxy network?
Is the domain in the Host(...) rule exactly right (incl. subdomain)? The dashboard
(step 7) shows under “HTTP Routers” whether the router was registered.The browser shows Traefik’s self-signed emergency certificate; the log reads
permissions 644 for /acme.json are too open, please use 600.
Traefik is running but
skipped the ACME resolver – hence no real certificate. Run
Read on: Setting up Traefik: reverse proxy with automatic HTTPS →chmod 600 acme.json (step
2) and restart the container.No app is routed; the Traefik log repeats client version 1.24 is too old. Minimum supported API version is 1.40.
Your Traefik version is too old for your Docker
engine – the Docker provider can no longer query the socket. Current Docker (Engine 29,
API level ≥ 1.40) needs Traefik ≥ v3.6; that’s why this tutorial uses
Read on: Setting up Traefik: reverse proxy with automatic HTTPS →traefik:v3.7. Reproduced against Docker 29: v3.5.6 runs into exactly this error,
v3.6.25 talks to the socket cleanly again. So older tags like v3.3 or v3.5 no
longer work with new Docker – bump the image tag and run docker compose up -d again.Basic auth on the dashboard is rejected immediately / the router is missing.
In the
Read on: Setting up Traefik: reverse proxy with automatic HTTPS →compose.yaml, the $ characters of the hash must be doubled ($$). Check the
hash once more outside with htpasswd -nbB.Gateway Timeout or Traefik doesn’t reach the container.
Usually the app is on the
wrong network, or Traefik doesn’t know which one is meant.
Read on: Setting up Traefik: reverse proxy with automatic HTTPS →providers.docker.network=proxy in Traefik and networks: [proxy] on the app must
match.502 Bad Gateway, even though the container is running.
Traefik reaches the
container but hits the wrong port. If the app doesn’t listen on 80, it needs the label
Read on: Setting up Traefik: reverse proxy with automatic HTTPS →traefik.http.services.<name>.loadbalancer.server.port=<real-port>. This exact case
meets you with the first app in the next tutorial (Uptime Kuma on 3001).dig returns no IP or a wrong (old) one.
Usually still propagation. Query a
public resolver specifically to bypass your local cache:
Read on: Connecting a domain to your server (DNS basics) →dig +short YOUR_DOMAIN @1.1.1.1. If it already shows the correct value, only your local/provider cache
hasn’t expired yet – wait.The domain resolves, but to the wrong IP – e.g. a registrar’s parking page.
Often
an old A record or a redirect/parking setting still exists. Remove contradictory
entries; per name and type there should be exactly one value (deliberate
exceptions aside).
Read on: Connecting a domain to your server (DNS basics) →IPv4 works, IPv6 (AAAA) leads to timeouts.
You entered an AAAA record even though
the server has no working IPv6 address. Browsers then prefer IPv6 and run into a
timeout. Remove the AAAA record until the server really supports IPv6.
Read on: Connecting a domain to your server (DNS basics) →In some interfaces the value is stored with a trailing dot (YOUR_DOMAIN.) and
you’re unsure.
The trailing dot (root of the DNS hierarchy) is normal and correct –
many DNS managers add it automatically. No reason to worry.
Read on: Connecting a domain to your server (DNS basics) →Emails sent from the server land in spam or are rejected (the mail log shows e.g.
does not resolve to address or no PTR record).
The reverse-DNS entry (PTR) is
missing or doesn’t match the sender hostname. Set the PTR as described in step 5 at
the VPS provider and make sure it points to the same name that also resolves via the
A/AAAA record.
Read on: Connecting a domain to your server (DNS basics) →did not find expected key (or similar YAML errors).
YAML is
indentation-sensitive – spaces only, never tabs, and consistent per level
(common: 2 spaces). Check the file without starting it:
Read on: Docker Compose: services, volumes, networks →docker compose config
reports the error with line and column (go-yaml load error in parser … at L2.C3-L4.C4 – the broken line is the second position).address already in use or port is already allocated on up.
The host port
(left in
Read on: Docker Compose: services, volumes, networks →8080:80) is already taken – in the first case by a program on the server, in
the second by another container (docker ps shows which). Find the occupant with
sudo ss -tlnp | grep 8080 or choose a different host port.An app can’t find its database (could not translate host name).
The hostname
must be the service name (e.g.
Read on: Docker Compose: services, volumes, networks →db), not localhost. Inside a container,
localhost is the container itself, not the neighboring service. And: both services
must be in the same Compose project (the same file).Docker Compose: After docker compose down all data is gone.
Either the volume wasn’t declared
as a named volume under
Read on: Docker Compose: services, volumes, networks →volumes: (then it was only the ephemeral container
storage), or down -v was used. Always run persistent services with a declared named
volume.docker-compose: command not found.
That’s the old Compose v1 (with a hyphen).
The current one is
Read on: Docker Compose: services, volumes, networks →docker compose (with a space, plugin). If it’s missing: sudo apt install docker-compose-plugin (see Docker
tutorial).“Create” won’t make a snapshot while a DVD is inserted.
If an .iso image is attached
in the virtual drive under “Media → DVD Drive”, the SCP refuses new snapshots. Eject the
image there (the ISO row in the server overview has to show
Read on: netcup SCP: snapshots, console & rescue →- again) and start the
snapshot once more.The snapshot can’t be created because there isn’t enough disk space.
A snapshot needs
room next to your live data. Clean up on the server, hand the freed blocks back to the
host with
Read on: netcup SCP: snapshots, console & rescue →fstrim -av, and delete snapshots you no longer need. If that doesn’t help,
trigger the Storage Optimization in the SCP under “Media → Disks”. Plan for
downtime: netcup shuts the server down for it, optimizes the disk and boots it again.After an online snapshot restore, the database is corrupted.
An online snapshot may
catch a running write mid-way. For servers with a database, take an offline snapshot
or create a database dump beforehand.
Read on: netcup SCP: snapshots, console & rescue →You can’t get into the SCP.
The SCP uses its own credentials (not SSH). They are
in the welcome email; a forgotten SCP password you reset in the netcup customer account
(CCP).
Read on: netcup SCP: snapshots, console & rescue →After ufw enable you can no longer get in via SSH.
The SSH rule was missing or
targeted the wrong port. Connect via the console in the netcup SCP (VNC,
independent of SSH), allow your SSH port there (
Read on: Setting up a firewall with UFW →sudo ufw allow …) and test again.
That’s exactly what step 3 warns about.ERROR: Could not find a profile matching 'OpenSSH'.
The OpenSSH profile only
exists if
Read on: Setting up a firewall with UFW →openssh-server is installed. Use the port number instead: sudo ufw allow 22/tcp (or your port). sudo ufw app list shows the available profiles.A Docker container is reachable from outside even though UFW doesn’t open the port.
Not your mistake – Docker bypasses UFW. Docker writes its rules directly
into
Read on: Setting up a firewall with UFW →iptables and inserts them ahead of the UFW chains. A published container port
(ports: in the compose.yaml) is thus open, no matter what UFW says. The clean
solution is a second firewall layer in front of the server – at netcup the
firewall in the SCP as an upstream
perimeter. On the host it also helps to bind container ports only to 127.0.0.1
instead of 0.0.0.0.After activating, name resolution stops working (apt update hangs, ping domain.de
fails, but ping 1.1.1.1 works).
The DNS replies are being blocked. Check the rule in
the base template INBOUND UDP ACCEPT, Src port 53 (source port, not destination port).
Read on: Setting up the netcup firewall in the SCP →The clock drifts, or TLS certificates are rejected due to the wrong time.
The NTP
replies are missing. Add INBOUND UDP ACCEPT, Src port 123.
Read on: Setting up the netcup firewall in the SCP →IPv6 no longer works (v4 does).
The ICMPv6 rule is missing. Without Neighbor
Discovery, the server can’t even find its neighbor (router) over IPv6.
Read on: Setting up the netcup firewall in the SCP →After activating, you can no longer get in via SSH.
The SSH rule is missing or names the
wrong port. Via the VNC console (SCP → Display) you can still reach the server; correct
the policy and save again.
Read on: Setting up the netcup firewall in the SCP →The server can’t send emails (outbound port 25 doesn’t work).
Not an error in your
policy, but netcup’s default policy “netcup Mail block”. How to take it off is described
under unblock port 25.
Read on: Setting up the netcup firewall in the SCP →The server initially runs normally and is suddenly offline after one or two weeks.
If
the server uses DHCP, the lease renewal is blocked by the whitelist. Add
Read on: Setting up the netcup firewall in the SCP →INBOUND · UDP · ACCEPT · Src 67 to the base template (see the DHCP tip in step 2).E: Package 'docker-ce' has no installation candidate.
The package source from
step 2 is missing or malformed – apt only knows the name from the Debian packages'
dependencies and finds no package behind it. Check the contents of
Read on: Installing Docker on Debian →/etc/apt/sources.list.d/docker.list – it must contain your Debian version (e.g.
trixie) – and then run sudo apt update again.permission denied while trying to connect to the docker API at unix:///var/run/docker.sock.
The
Read on: Installing Docker on Debian →docker group membership hasn’t taken effect yet. End the SSH session and
reconnect; groups must then include docker. If not, repeat step 4.Conflicts during installation with already-present packages.
Another Docker
variant is already installed (
Read on: Installing Docker on Debian →docker.io, podman-docker, …). Remove the old
packages first: sudo apt remove docker.io docker-doc docker-compose podman-docker containerd runc – existing containers/images are preserved.docker compose reports docker: unknown command: docker compose.
The Compose
plugin is missing – Docker was probably installed differently earlier. Run
Read on: Installing Docker on Debian →sudo apt install docker-compose-plugin. Note: the old docker-compose (with a hyphen) is a
different, outdated tool.SSH keeps asking for the password despite ssh-copy-id.
Usually the file
permissions on the server are wrong: SSH ignores
Read on: Hardening SSH access →authorized_keys if group or
others may write to ~/.ssh. The log on the server (sudo journalctl -u ssh --since -5min) then shows Authentication refused: bad ownership or modes for directory /home/koch/.ssh. Fix it with chmod 700 ~/.ssh && chmod 600 ~/.ssh/authorized_keys, and also check that you’re connecting with the right user
(koch@…, not root@…).With Permission denied (publickey) you can’t get in at all anymore.
Password login was disabled before the key worked. Open the VNC console in the
netcup SCP, log in locally there, temporarily set
Read on: Hardening SSH access →PasswordAuthentication yes in /etc/ssh/sshd_config.d/00-harden-ssh.conf, restart SSH and start again at
step 2.After the restart the SSH service no longer starts.
The configuration has a
syntax error; a mistyped
Read on: Hardening SSH access →PasswordAuthentification is enough (hence sshd -t in
step 4). Log in via the VNC console; sudo sshd -t
then names file, line and option:
/etc/ssh/sshd_config.d/00-harden-ssh.conf: line 2: Bad configuration option: PasswordAuthentification, followed by … terminating, 1 bad configuration options.The settings seem to take effect, but password login still works.
Your file isn’t the
first one to set the value (see “The first value wins”). If
Read on: Hardening SSH access →sshd -T from step 4 shows
yes, check with ls /etc/ssh/sshd_config.d/ whether another file sorts before yours and
whether yours really ends in .conf. The Include line only picks up those. Then restart SSH.ssh: connect to host … port 22: Connection timed out.
Usually the IP was
mistyped or the server isn’t fully provisioned yet. Check the IP in your customer
account and whether the server is shown as “online” there. Wait a few minutes
after ordering.
Read on: First steps with a netcup VPS →Permission denied, please try again on root login.
Wrong password, often a
copy-paste issue with invisible trailing spaces, or a different keyboard layout.
Copy the password without surrounding spaces directly from the credentials.
Read on: First steps with a netcup VPS →WARNING: REMOTE HOST IDENTIFICATION HAS CHANGED!.
The server was reinstalled
and has a new host key, and SSH rightly raises the alarm. If you reinstalled it,
remove the old entry with
Read on: First steps with a netcup VPS →ssh-keygen -R YOUR_SERVER_IP and reconnect. If you
didn’t reinstall, investigate before you connect.sudo: command not found as the new user.
On minimal images the package is
sometimes missing. Install it as
Read on: First steps with a netcup VPS →root: apt install sudo. Then check that the
user is in the group: groups koch must contain sudo, otherwise repeat step 3
and log out and back in once.Nothing found. Try fewer words, or the literal error message.