rkt - The Pod-Native Container Engine: Deployment and Usage Guide

Note: The rkt project has officially ended, and all development and maintenance activities have halted. This guide is provided for historical context and for those interested in forking or experimenting with the codebase. It is recommended that any new development proceeds with an explicit rename and rebranding.

1. Prerequisites

Before you begin, ensure you have the following installed on your system:

Go (Golang): rkt is written in Go. You will need Go 1.11 or later to build the project.
- Download and install Go
Git: For cloning the rkt repository.
- Download and install Git
Linux Environment: rkt is a container engine for Linux.
Basic Build Tools: make, gcc (or equivalent C compiler), and other standard build utilities may be required.
- On Debian/Ubuntu: sudo apt-get install build-essential
- On Fedora/RHEL: sudo yum install @development-tools

2. Installation

Since the project is no longer actively maintained, direct installation via package managers might be outdated or unavailable. The recommended approach is to build from source.

Clone the rkt repository:

git clone https://github.com/rkt/rkt.git
cd rkt

Verify Go environment:

Ensure your GOPATH is set correctly and Go is in your PATH.
```
go env GOPATH
go version
```
Build rkt:

The project includes a Makefile for building.
```
make
```
This command will compile the rkt binaries and place them in the bin/ directory within the project root.
Install rkt (optional, for system-wide access):

To make rkt accessible from anywhere, you can move the compiled binaries to a directory in your system's PATH, such as /usr/local/bin.
```
sudo make install
```
Alternatively, add the bin/ directory to your PATH environment variable:
```
export PATH=$PATH:$(pwd)/bin
```
Verify installation:
```
rkt version
```
You should see the rkt version information if the installation was successful.

3. Configuration

rkt's configuration is primarily handled through command-line flags and specific environment variables for certain functionalities. There are no global configuration files like rkt.conf in the traditional sense.

Environment Variables:
- RKT_INSECURE_OPTIONS: Controls insecure options for image fetching and execution.
- RKT_PATH: Specifies the path to the rkt executable (usually not needed if rkt is in your PATH).
- Specific environment variables for networking (CNI), SELinux, and KVM are detailed in the rkt documentation (e.g., Documentation/networking.md, Documentation/selinux.md, Documentation/running-kvm-stage1.md).
Networking (CNI): rkt uses the Container Networking Interface (CNI) specification. CNI configuration files (.conflist or .conf) are typically placed in /etc/cni/net.d/. Refer to the CNI documentation for details on creating these files.
Image Discovery: rkt discovers images based on their name. For example, rkt run coreos.com/etcd:v3.3.12. It can fetch images from various sources, including HTTP(S) and local files.

4. Build & Run

Running a Container (Pod)

rkt's basic unit of execution is a pod. You can run Docker images, OCI images, or App Container Images (ACI).

Run a simple Docker image:

rkt can directly run Docker images.
```
rkt run docker://alpine --exec /bin/echo -- "Hello from rkt!"
```
This command fetches the alpine Docker image, creates a pod, and executes /bin/echo "Hello from rkt!" inside it.
Run an ACI image (example using coreos/etcd):
```
# Fetch the image
rkt fetch coreos.com/etcd:v3.3.12

# Run the image
rkt run coreos.com/etcd:v3.3.12 -- --version
```
The -- separates rkt arguments from arguments passed to the application inside the container.
Interactive shell:
```
rkt run docker://alpine --exec /bin/sh
```
This will drop you into an interactive shell inside the Alpine container.
Listing running pods:
```
rkt list
```
Stopping a pod:
```
rkt stop <pod-uuid>
```
Replace <pod-uuid> with the UUID obtained from rkt list.
Removing a pod:
```
rkt rm <pod-uuid>
```

5. Deployment

Given rkt's project status, direct deployment to cloud platforms or orchestration systems is not actively supported or recommended. However, rkt was designed for integration with:

systemd: rkt can be integrated with systemd to manage pods as system services.
- Refer to Documentation/using-rkt-with-systemd.md for details.
Kubernetes: rkt was intended as an alternative container runtime for Kubernetes.
- Refer to Documentation/using-rkt-with-kubernetes.md for historical integration details.
Nomad: Integration with HashiCorp Nomad was also a goal.
- Refer to Documentation/using-rkt-with-nomad.md for historical integration details.

For modern container deployments, it is strongly recommended to use actively maintained container runtimes like containerd or CRI-O with Kubernetes, or Docker/Podman for standalone deployments.

If you are using rkt in a legacy environment or for experimental purposes:

Prepare your rkt host: Install rkt as described in the Installation section.
Configure networking: Set up CNI plugins and configuration files (/etc/cni/net.d/) as needed for your network topology.
Define pods: Create scripts or systemd units to define and run your rkt pods.
Image management: Ensure rkt can access the container images (Docker, ACI, OCI) you intend to run. This may involve pre-fetching images or configuring image registries.

6. Troubleshooting

"rkt: command not found"
- Solution: Ensure the rkt executable is in your system's PATH or that you are running it from the bin/ directory of the cloned repository. If you used sudo make install, verify /usr/local/bin is in your PATH.
"Error fetching image: ... certificate signed by unknown authority"
- Cause: This usually happens when fetching images from HTTPS registries with self-signed or untrusted certificates.
- Solution: Use the --insecure-options=image flag for testing purposes (not recommended for production), or properly configure your system's certificate authorities.
```
rkt run --insecure-options=image docker://my-insecure-registry/my-image
```
Networking issues (pod cannot reach external network or other pods)
- Cause: Incorrect CNI configuration or missing CNI plugins.
- Solution:
  1. Verify CNI plugins are installed (e.g., bridge, host-local).
  2. Check CNI configuration files in /etc/cni/net.d/ for correct syntax and network definitions.
  3. Ensure the CNI plugin executables are in a directory specified by CNI_PATH or /opt/cni/bin.
"Error: permission denied" or similar access issues
- Cause: rkt often requires elevated privileges for certain operations (e.g., setting up network namespaces, mounting filesystems).
- Solution: Run rkt commands with sudo if necessary. However, be cautious when running container engines with root privileges.
Pod fails to start with generic errors
- Solution: Increase verbosity for more detailed logs.
```
rkt --debug run ...
```
  Examine the output for specific error messages related to image parsing, execution environment, or application startup.
Project End-of-Life: Remember that rkt is no longer maintained. If you encounter bugs or issues that are not easily resolved, there will be no official support or new releases. Consider migrating to actively maintained container runtimes for production use cases.

How to Deploy & Use rkt/rkt