Sysbox Installer for dstack

A Docker-based installer for Sysbox on read-only dstack systems.

Quick Start

Build the Installer

cd installer
chmod +x build.sh
./build.sh sysbox-installer latest

Install Sysbox

Single command installation in a CVM:

docker run --rm --privileged --pid=host --net=host -v /:/host \
  dstacktee/dstack-sysbox-installer:1.0.0

That's it! The installer will:

Check for existing installations
Build and install Sysbox from source
Handle /etc volatile overlay mount preserving configs
Configure Docker runtime using Sysbox's official script
Create transient systemd services and start daemons

Manual Steps (if needed)

Interactive Installation

docker run -it --rm --privileged --pid=host --net=host -v /:/host \
  dstacktee/dstack-sysbox-installer:1.0.0 bash

Then run: /usr/local/bin/install-sysbox-complete.sh

Check Build Information

docker run --rm dstacktee/dstack-sysbox-installer:1.0.0 cat /usr/local/share/BUILD_INFO

Usage After Installation

Run Containers with Sysbox

# Basic system container
docker run --runtime=sysbox-runc -it ubuntu bash

# Docker-in-Docker
docker run --runtime=sysbox-runc -d --name docker-container docker:dind

# Kubernetes-in-Docker
docker run --runtime=sysbox-runc -d --name k8s-node kindest/node:latest

Manage Sysbox Services

# Check status
systemctl status sysbox-mgr sysbox-fs

# Restart services
systemctl restart sysbox-mgr sysbox-fs

# View logs
journalctl -u sysbox-mgr -u sysbox-fs

File Structure

installer/
├── build.sh                           # Build script
├── README.md                          # This file
├── docker/
│   └── Dockerfile                     # Multi-stage build with source compilation
└── scripts/
    ├── install-sysbox-complete.sh     # Main installation script
    ├── verify-downloads.sh            # SHA256 verification for downloads
    ├── sysbox-mgr.service            # systemd service for sysbox-mgr
    └── sysbox-fs.service             # systemd service for sysbox-fs

Technical Details

What the Installer Does

Checks existing installation - Detects and reports existing Sysbox installations
Copies binaries - Places Sysbox binaries in /usr/bin (writable location)
Sets up /etc overlay - Creates volatile overlay preserving existing configs (WireGuard, Docker)
Creates symlinks - Links fusermount, modprobe, iptables for Sysbox requirements
Configures Docker - Uses Sysbox's official docker-cfg script to properly merge runtime configuration
Creates systemd services - Installs transient service files in /run/systemd/system
Starts services - Starts Sysbox manager and filesystem daemons

Data Locations

Sysbox data: /dstack/persistent/sysbox-data
Binaries: /usr/bin

Security

All downloads verified with SHA256 checksums
Sysbox built from official Git repository (recursive clone)
Uses specific version tags (v0.6.7)
Proper systemd service isolation

Troubleshooting

Check Service Status

systemctl status sysbox-mgr sysbox-fs
journalctl -u sysbox-mgr -u sysbox-fs

Verify Docker Runtime

docker info | grep -A5 Runtimes

Test Basic Functionality

docker run --runtime=sysbox-runc --rm alpine echo "Test successful"

Clean Installation

systemctl stop sysbox-mgr sysbox-fs
systemctl disable sysbox-mgr sysbox-fs
rm -f /run/systemd/system/sysbox-*.service
systemctl daemon-reload
umount /etc  # If volatile overlay mounted
rm -rf /dstack/persistent/sysbox-*

Requirements

Docker installed and running
Privileged container execution
dstack system with ZFS persistent storage
systemd for service management

Release and Verification

Creating a Release

Releases are automated via GitHub Actions with sigstore attestation:

Tag a new version:
```
git tag v1.0.0
git push origin v1.0.0
```
The workflow will automatically:
- Build the Docker image
- Push to Docker Hub
- Generate sigstore attestation
- Create a GitHub release

Verifying Image Attestation

All released images are signed with sigstore for supply chain security:

# Install cosign
curl -O -L "https://github.com/sigstore/cosign/releases/latest/download/cosign-linux-amd64"
sudo mv cosign-linux-amd64 /usr/local/bin/cosign
sudo chmod +x /usr/local/bin/cosign

# Verify the image (replace VERSION and DIGEST)
cosign verify-attestation \
  --type https://slsa.dev/provenance/v1 \
  --certificate-identity-regexp "^https://github.com/Dstack-TEE/dstack-sysbox-installer/.github/workflows/release.yml@refs/tags/vVERSION$" \
  --certificate-oidc-issuer https://token.actions.githubusercontent.com \
  docker.io/Dstack-TEE/dstack-sysbox-installer@sha256:DIGEST

You can also verify on Sigstore Search.

Support

For issues with the installer, check:

Docker daemon is running
Container has privileged access
/dstack/persistent/ is available and writable
systemd is available on the host

For Sysbox issues, see: https://github.com/nestybox/sysbox

GeezerVison

Latest commit

History

Folders and files

Repository files navigation