Install from a package
Since 0.7 the agent is also published as a Debian and an RPM package, for a server where it should be a service of the host — started by systemd, upgraded by the package manager, its output in the journal — instead of a container. This page covers what the package installs and what it does not, starting everything, where the API listens, and upgrading and removing.
The installer remains the shortest way to a running server, and sets up everything in one run. The package is for the server whose owner wants the agent managed like the other services of the machine.
Before you begin
You need:
- A Linux server with systemd, amd64 or arm64. The
.debis for Debian and Ubuntu; the.rpmis built on Rocky Linux 9 and installs on 8 and later, and on Fedora. Since 0.9 both are installed and put through everything an installation does — deployments, rollbacks, backups, an export and an import — on Debian and Rocky Linux, in containers of those distributions inside a Docker daemon of their own (scripts/test-package.shin the repository, not part of CI); what runs there is the agent with the unit's environment and the proxy from the package's compose file, not systemd, SELinux enforcing, a host firewall or the dashboard. - Docker Engine with the Compose plugin, from your distribution or from Docker. The package recommends Docker and does not depend on one packaging of it.
- Ports 80 and 443 free and reachable from the internet, as for any installation.
Install the package
Each release has four packages: shipwick-agent_amd64.deb, shipwick-agent_arm64.deb, shipwick-agent_amd64.rpm and shipwick-agent_arm64.rpm. They are files of the release, listed in its checksums.txt like the others. Since 0.8.0 that file is signed, and Verify a release has the command that verifies it; the packages carry no signature of their own, and there is no package repository.
curl -fsSLO https://github.com/shipwick/shipwick/releases/latest/download/shipwick-agent_amd64.deb
curl -fsSL https://github.com/shipwick/shipwick/releases/latest/download/checksums.txt | grep shipwick-agent_amd64.deb | sha256sum -c
sudo apt install ./shipwick-agent_amd64.deb # or: sudo dnf install ./shipwick-agent_amd64.rpmThe file names carry no version, so releases/latest/download/ is always the latest release; the version is inside the package.
The installation ends by saying what to do next:
The Shipwick agent is installed and not started.
1. It needs Docker Engine on this server (https://docs.docker.com/engine/install/).
2. Its settings, with a generated API token: /etc/shipwick/agent.env
3. Start it now and at boot: systemctl enable --now shipwick-agent
4. The reverse proxy and the dashboard run as containers:
docker compose --env-file /etc/shipwick/agent.env -f /usr/share/shipwick/compose.yml up -d
What this package covers, and what it does not: handbook §4, "Installation from a package".What the package installs
/usr/bin/shipwick-agent: the agent.shipwick-agent.service: a systemd unit. It reads the agent's settings from the next file./etc/shipwick/agent.env: the agent's settings, oneNAME=valuea line. Written on the first installation with a generated API token, readable by root only, and never touched again./var/lib/shipwick: the agent's data directory, with the database, the encryption key and the backups./usr/share/shipwick/compose.yml: a compose file for the proxy and the dashboard, pinned to the package's version.
It starts nothing and enables nothing: the agent needs Docker, and when it runs is your decision.
What it does not install
- Docker. Install it from your distribution or from Docker.
- The CLI.
curl -fsSL https://get.shipwick.com | sh -s -- --cli, or any way in Install the CLI. - The proxy and the dashboard as programs of the host. Those two stay containers. Caddy finds the replicas of an application by name on a Docker network, which a Caddy installed on the host cannot do; static applications are copied into its container, and requests are counted from its output. The dashboard needs Node, which the package does not bring. The compose file starts both.
Start it
systemctl enable --now shipwick-agent
docker compose --env-file /etc/shipwick/agent.env -f /usr/share/shipwick/compose.yml up -dIn that order: the agent creates the three Docker networks the compose file joins. The agent finds the proxy by the compose project shipwick and the service caddy, and talks to it through a socket in /run/shipwick.
The API token is SHIPWICK_AGENT_TOKEN in /etc/shipwick/agent.env. It is the root token: keep the file private.
Where the API listens
As installed, on 127.0.0.1:9000. The CLI on the server reaches it:
shipwick login --url http://127.0.0.1:9000A laptop reaches it through an SSH tunnel.
The proxy and the dashboard are containers, and a container does not reach the host's loopback.
- For the API at a hostname, set
SHIPWICK_AGENT_DOMAIN. Since 0.8 the agent then also listens on the address the server has on theshipwick-controlnetwork, which is where the proxy is sent; there it answers the addresses of that network only. - For the dashboard, the agent listens on the address of Docker's bridge instead of loopback.
ip -4 addr show docker0shows it; it is172.17.0.1unless Docker was configured otherwise.
With both:
# /etc/shipwick/agent.env
SHIPWICK_LISTEN_ADDR=172.17.0.1:9000
SHIPWICK_AGENT_DOMAIN=agent.example.com
SHIPWICK_DASHBOARD_DOMAIN=dashboard.example.comThen restart the agent:
systemctl restart shipwick-agentThose addresses are reachable from the containers of this server and from nowhere else, and the agent refuses the containers of applications there: see Who can reach the API. A firewall on the server that filters traffic from Docker's networks (ufw, firewalld) must let port 9000 through from the shipwick-control network.
One thing an agent of the host sees that an agent in a container cannot: the size of the kernel's table of neighbours, net.ipv4.neigh.default.gc_thresh3, which the kernel shows in the host's own network namespace only. Since 0.9 GET /server carries it as kernel_limits.neighbour_table, and shipwick doctor warns from a quarter of the table on; see Prepare a server.
Never give the API a public address
The API is plain HTTP. On a public address the token travels in clear text, and an admin token is root on the server. The ways in are the proxy, over HTTPS, and the server itself.
Every other setting goes into the same file, one line each, followed by a restart; they are listed in Agent configuration.
The agent runs as root
It drives Docker through Docker's socket, and whoever may do that can start a container that owns the host. A user of its own in the docker group would be root in everything but name, and the proxy's admin socket and root's docker login credentials would need opening up for it.
It holds the socket itself, by design. The socket proxy that stands between the agent and Docker on a server the installer set up, since 1.1, is a container of that installation's compose file; the package has no container for the agent to depend on and keeps the arrangement a process of the host has always had. The agent says so: docker.socket: "direct" in GET /server, holding the Docker socket at the end of the Docker line of shipwick server status, and a hint in shipwick doctor that names the package as one of the two places this is expected. On a server installed from a package the hint is expected, and there is nothing to do about it. See The Docker socket.
The unit takes away what the agent does not need instead: it cannot gain privileges, /usr, /boot and /etc are read-only to it, home directories are read-only, and it has a /tmp of its own. A SHIPWICK_BACKUP_DIR must therefore lie outside those, under /var or /srv.
SELinux
Reasoned, not run: the packages were installed and run on Debian and Rocky Linux in containers, where nothing enforces. On Rocky Linux and RHEL with SELinux enforcing, a service systemd starts from a binary no policy module describes runs as unconfined_service_t, which SELinux leaves alone, and the package ships no module: the agent's connection to Docker's socket, its files under /var/lib/shipwick and its connection to the proxy's socket in /run/shipwick are all permitted on its side.
What is expected to be denied is on the containers' side, and only once Docker labels them ("selinux-enabled": true in /etc/docker/daemon.json, which Docker's own packages leave off):
- The proxy creating its admin socket in
/run/shipwick, a directory of the host labelledvar_run_t, ascontainer_t: inausearch -m AVC -ts recentadenied { create }withtclass=sock_file.:zon the mount (/run/shipwick:/run/shipwick:z) labels the directorycontainer_file_t; the package replacescompose.ymlat each upgrade, so keep the change in a copy of the file and start the proxy from that. - The dashboard connecting to the agent's port, should that port's type be one containers may not connect to.
setsebool -P container_connect_any 1lets containers connect to any port of the host.
For anything else, ausearch -m AVC -ts recent | audit2allow -M shipwick-local && semodule -i shipwick-local.pp writes and installs a local module that allows exactly what was denied; read it before installing it. Confining the agent itself would be a policy module of your own.
Upgrade
Upgrading is installing the newer package. The agent is restarted when it was running, and agent.env stays as it is. The compose command, run again, brings the proxy and the dashboard to the same version:
sudo apt install ./shipwick-agent_amd64.deb
docker compose --env-file /etc/shipwick/agent.env -f /usr/share/shipwick/compose.yml up -dComing from 0.7, the compose command is not optional
It moves the proxy and the dashboard onto the shipwick-control network. Until it has run, the agent refuses both, as it refuses any container that calls from an application network.
The upgrade of the installer's installation was walked from every release; the packages were not. Since 0.9 the packages are installed and run on Debian and Rocky Linux by a script of the repository, as described above. See Upgrade Shipwick.
The notice about a newer release in shipwick server status names the installer. On a server installed from a package, the package is what to install.
Remove
Removing the package stops the agent and leaves the applications running, unsupervised: they are containers of Docker. agent.env goes with apt purge. /var/lib/shipwick — the database and the key that decrypts it — is never removed by the package.
The installer and the package are two installations
An installation made by the installer keeps its data in a Docker volume; one made from a package keeps it in /var/lib/shipwick. To move from one to the other, export and import: see Move to a new server.
What's next
- Deploy your first application.
- Agent configuration: every variable that can go into
agent.env. - Upgrade Shipwick: what happens to running applications while the agent restarts.
- Security: what the API token is worth.
- Prepare a server: SSH keys, security updates, swap, a firewall, backups elsewhere.