166 lines
4.7 KiB
Text
166 lines
4.7 KiB
Text
# 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:
|
|
|
|
```bash
|
|
install -Dm0644 deploy/rancher/registries.yaml \
|
|
"$HOME/.config/kubectl/registries.yaml"
|
|
```
|
|
|
|
Its content is:
|
|
|
|
```yaml
|
|
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
|
|
|
|
```bash
|
|
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
|
|
|
|
```bash
|
|
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`:
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
curl --fail http://127.0.0.1:30080/api/health
|
|
```
|
|
|
|
Retrieve the one-time bootstrap password locally, open
|
|
`https://127.0.0.1:8443`, and immediately choose a permanent administrator
|
|
password:
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
docker ps --filter name='^/rancher$'
|
|
docker logs --tail 200 rancher
|
|
```
|
|
|
|
Restart Rancher:
|
|
|
|
```bash
|
|
docker restart rancher
|
|
```
|
|
|
|
Create a consistent backup:
|
|
|
|
```bash
|
|
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.
|