Rancher single-server installation

This runbook reproduces the local Rancher management instance installed on the dedicated server. It binds Rancher only to loopback; Nginx and Certbot provide public access separately.

This Docker-based Rancher installation is appropriate for a single-server, non-HA environment. A production environment that requires control-plane high availability should run Rancher with its Helm chart on a dedicated multi-node Kubernetes cluster instead of copying this single-container topology.

Installed versions and paths

Rancher: v2.15.1
Image: rancher/rancher@sha256:5f6c4dc52a05e0c400b53c08bf778ca55790f277e443b5881269158499b7ebe5
Persistent data: /opt/rancher
Registry configuration: ~/.config/kubectl/registries.yaml
Local HTTP: http://127.0.0.1:8000
Local HTTPS: https://127.0.0.1:8443
Development application NodePort: http://127.0.0.1:30080
Production application NodePort: http://127.0.0.1:31374

Pinning the digest makes another installation reproducible. Review and update the Rancher version deliberately rather than running an unpinned latest image in production.

1. Configure the HTTP image registry

The source file is committed at deploy/rancher/registries.yaml. Install it:

install -Dm0644 deploy/rancher/registries.yaml \
  "$HOME/.config/kubectl/registries.yaml"

Its content is:

mirrors:
  "batty1039.startdedicated.net:5000":
    endpoint:
      - "http://batty1039.startdedicated.net:5000"

configs:
  "batty1039.startdedicated.net:5000":
    tls:
      insecure_skip_verify: true

The original draft contained duplicate YAML keys. Duplicate keys are invalid for this purpose because parsers may silently discard one occurrence.

2. Prepare persistent storage

sudo install -d -m 0755 /opt/rancher

Back up this directory before Rancher upgrades. It contains the embedded K3s management cluster and all Rancher state.

3. Pull and run Rancher

docker pull \
  rancher/rancher@sha256:5f6c4dc52a05e0c400b53c08bf778ca55790f277e443b5881269158499b7ebe5

docker run -d \
  --restart=unless-stopped \
  -p 127.0.0.1:8000:80 \
  -p 127.0.0.1:8443:443 \
  -p 127.0.0.1:30080:30080 \
  -p 127.0.0.1:31374:31374 \
  -v /opt/rancher:/var/lib/rancher \
  -v "$HOME/.config/kubectl/registries.yaml:/etc/rancher/k3s/registries.yaml:ro" \
  --privileged \
  --name rancher \
  rancher/rancher@sha256:5f6c4dc52a05e0c400b53c08bf778ca55790f277e443b5881269158499b7ebe5

The explicit 127.0.0.1 bindings prevent Rancher and application NodePorts from being published directly to the internet. Nginx on the same server can still reach them. Docker cannot add port mappings to an existing container, so new NodePorts must be included when recreating the Rancher container.

4. Verify the installation

Wait until the readiness endpoint returns pong:

until curl -ksSf https://127.0.0.1:8443/ping | grep -q pong; do
  sleep 5
done

docker ps --filter name='^/rancher$'
docker exec rancher kubectl get nodes -o wide

Expected results:

The container is running with restart policy unless-stopped.
Only loopback ports 8000, 8443, 30080, and 31374 are published.
https://127.0.0.1:8443/ping returns pong.
The embedded local-node reports Ready.

After deploying Go Guess, verify the application NodePort:

curl --fail http://127.0.0.1:30080/api/health

Production PostgreSQL and RabbitMQ require persistent volumes. Install the single-node local-path provisioner before the production Helm release:

make rancher-storage
make helm-deploy-production

The provisioner stores data under /var/lib/rancher/k3s/storage, which is inside the persistent /opt/rancher host mount. Its StorageClass uses a Retain reclaim policy so deleting a claim does not automatically delete the underlying production data.

Retrieve the one-time bootstrap password locally, open https://127.0.0.1:8443, and immediately choose a permanent administrator password:

docker logs rancher 2>&1 |
  sed -n 's/.*Bootstrap Password: //p' |
  tail -n 1

Do not save that password in this repository.

5. Add Nginx and Certbot separately

For a public Rancher hostname, configure one.com DNS to point at the dedicated server. Proxy Nginx to https://127.0.0.1:8443, enable WebSocket upgrade headers, and disable upstream certificate verification because Rancher's local certificate is self-signed. Then request the public certificate:

sudo certbot --nginx -d rancher.urpi.be
sudo certbot renew --dry-run

Expose only public TCP ports 80 and 443. Keep 8000 and 8443 bound to loopback as configured above.

Operations

Inspect status and logs:

docker ps --filter name='^/rancher$'
docker logs --tail 200 rancher

Restart Rancher:

docker restart rancher

Create a consistent backup:

docker stop rancher
sudo tar -C /opt -czf "rancher-backup-$(date +%Y%m%d-%H%M%S).tar.gz" rancher
docker start rancher

Before an upgrade, read the Rancher release notes and compatibility matrix, back up /opt/rancher, pull a specifically pinned replacement image, remove only the stopped rancher container, and recreate it with the same mounts and port bindings.

5.2 KiB Raw Blame History