zosbuilder/components/zinit/docs/installation.md

Installing Zinit

This guide provides detailed instructions for installing Zinit on various platforms.

System Requirements

Zinit has minimal system requirements:

• Linux-based operating system
• Root access (for running as init system)

Pre-built Binaries

If pre-built binaries are available for your system, you can install them directly:

# Download the binary (replace with actual URL)
wget https://github.com/threefoldtech/zinit/releases/download/vX.Y.Z/zinit-x86_64-unknown-linux-musl

# Make it executable
chmod +x zinit-x86_64-unknown-linux-musl

# Move to a location in your PATH
sudo mv zinit-x86_64-unknown-linux-musl /usr/local/bin/zinit

Building from Source

Prerequisites

To build Zinit from source, you'll need:

• Rust toolchain (1.46.0 or later recommended)
• musl and musl-tools packages
• GNU Make

Install Rust

If you don't have Rust installed, use rustup:

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
source $HOME/.cargo/env

Install musl development tools

On Debian/Ubuntu:

sudo apt update
sudo apt install musl musl-tools

On Fedora:

sudo dnf install musl musl-devel

On Alpine Linux (musl is already the default libc):

apk add build-base

Build Process

1. Clone the repository:

git clone https://github.com/threefoldtech/zinit.git
cd zinit

2. Build using make:

make

This will create a statically linked binary at target/x86_64-unknown-linux-musl/release/zinit.

3. Install the binary:

sudo cp target/x86_64-unknown-linux-musl/release/zinit /usr/local/bin/

Development Build

For development or debugging:

make dev

Docker Installation

Using the Provided Dockerfile

Zinit includes a test Docker image:

# Build the Docker image
make docker

# Run the container
docker run -dt --device=/dev/kmsg:/dev/kmsg:rw zinit

Don't forget to port-forward a port to get access to the Zinit proxy using the -p XXXX:YYYY flag when running the container.

Custom Docker Setup

To create your own Dockerfile with Zinit:

FROM alpine:latest

# Install dependencies if needed
RUN apk add --no-cache bash curl

# Copy the zinit binary
COPY zinit /usr/local/bin/zinit
RUN chmod +x /usr/local/bin/zinit

# Create configuration directory
RUN mkdir -p /etc/zinit

# Add your service configurations
COPY services/*.yaml /etc/zinit/

# Set zinit as the entrypoint
ENTRYPOINT ["/usr/local/bin/zinit", "init", "--container"]

Using Zinit as the Init System

To use Zinit as the init system (PID 1) on a Linux system:

On a Standard Linux System

1. Install Zinit as described above
2. Create your service configurations in /etc/zinit/
3. Configure your bootloader to use zinit as init

For GRUB, add init=/usr/local/bin/zinit to the kernel command line:

# Edit GRUB configuration
sudo nano /etc/default/grub

# Add init parameter to GRUB_CMDLINE_LINUX
# Example:
# GRUB_CMDLINE_LINUX="init=/usr/local/bin/zinit"

# Update GRUB
sudo update-grub

In a Container Environment

For containers, simply set Zinit as the entrypoint:

docker run -dt --device=/dev/kmsg:/dev/kmsg:rw \
  --entrypoint /usr/local/bin/zinit \
  your-image init --container

First-time Setup

After installation, you'll need to create a basic configuration:

1. Create the configuration directory:

sudo mkdir -p /etc/zinit

2. Create a simple service configuration:

cat << EOF | sudo tee /etc/zinit/hello.yaml
exec: "echo 'Hello from Zinit!'"
oneshot: true
EOF

3. Test Zinit without running as init:

# For testing only - doesn't replace system init
sudo zinit init

If all is working correctly, you should see Zinit start and run your service.