Getting Started

Getting Started with RF Swift 🚀

This guide will help you get started with RF Swift by covering system requirements, installation steps, and next actions. First we will need to setup the environment.

Installation

RF Swift now offers a streamlined one-line installer that automatically installs all dependencies and configures your system for optimal performance.

Our new installer takes care of everything for you in a single command! It will:

• Install Docker or Podman (your choice) if not already present
• Download and install the latest RF Swift release
• Configure your system for USB, audio, and GUI support
• Create a convenient shell alias for easy access
• Set up proper permissions and configurations

curl -fsSL "https://raw.githubusercontent.com/PentHertz/RF-Swift/refs/heads/main/get_rfswift.sh" | sh

curl -fsSL "https://raw.githubusercontent.com/PentHertz/RF-Swift/refs/heads/main/get_rfswift.sh" | sh

The installer will detect your system and prompt you to choose a container engine if none is found:

📝 Which container engine would you like to install?
   🐳 Docker  — Industry standard, requires daemon (root)
   🦭 Podman  — Daemonless, rootless by default
1) Docker   2) Podman   3) Both   4) Skip

If both engines are already installed, RF Swift will auto-detect the available one at runtime.

Choosing a Container Engine

RF Swift supports both Docker and Podman as container engines. All RF Swift images are OCI-compatible and work identically with either engine.

Manual Installation

If you prefer to have more control over the installation process, you can install the components separately.

Linux Manual Installation

Essential Components

# Install Docker via official script
curl -fsSL https://get.docker.com | sudo sh

# Add your user to the docker group
sudo usermod -aG docker $USER
newgrp docker

# Verify installation
docker run hello-world

# Debian / Ubuntu
sudo apt install podman podman-compose slirp4netns fuse-overlayfs uidmap

# Fedora / RHEL
sudo dnf install podman podman-compose slirp4netns fuse-overlayfs

# Arch Linux
sudo pacman -S podman podman-compose slirp4netns fuse-overlayfs crun

# macOS (via Homebrew)
brew install podman
podman machine init && podman machine start

# Ensure subordinate UID/GID ranges are set
sudo usermod --add-subuids 100000-165535 $USER
sudo usermod --add-subgids 100000-165535 $USER

# Enable lingering so containers survive logout
sudo loginctl enable-linger $USER

# Enable the Podman socket (Docker API compatibility)
systemctl --user enable --now podman.socket

podman run hello-world

Other Essential Components

• xhost: Required for GUI application support (install via your distribution’s package manager)
• PulseAudio/PipeWire: Required for audio support (install via your distribution’s package manager)

Optional Components

• Go Compiler: Required if you want to build RF Swift from source
• BuildX: Required for cross-architecture compilation (Docker only)
• asciinema: Required for recording sessions

Repository Installation

# Clone the repository
git clone https://github.com/PentHertz/RF-Swift.git
cd RF-Swift

# Run the installation script to automatically install all dependencies
./install.sh

The install.sh script will:

• Offer to install Docker, Podman, or both
• Set up BuildX for cross-architecture support (Docker)
• Configure rootless mode (Podman)
• Install Go compiler if needed
• Configure xhost for GUI application access
• Set up PulseAudio/PipeWire for sound
• Configure user permissions
• Download and install the latest RF Swift binary

sudo usermod -aG docker $USER
newgrp docker

# Check your ranges
grep $USER /etc/subuid /etc/subgid

# If empty, add them
sudo usermod --add-subuids 100000-165535 $USER
sudo usermod --add-subgids 100000-165535 $USER

# Some distros provide podman-docker package
sudo apt install podman-docker   # Debian/Ubuntu
sudo dnf install podman-docker   # Fedora

Windows Manual Installation

Required Software

• Docker Desktop to run containers
• usbipd to bind USB devices to the host

For Audio Support

For programs requiring PulseAudio:

1. Follow the setup guide on Linux Uprising
2. Use the updated binaries available at pgaskin.net/pulseaudio-win32

Installation Steps

1. Install Docker Desktop (or Podman via WSL2) and ensure WSL2 integration is enabled
2. Install usbipd for USB device support
3. Set up PulseAudio if audio functionality is needed
4. Download the latest RF Swift binary from the releases page

macOS Manual Installation

Current Status

• Container functionality works without USB forwarding
• For full functionality including USB device support, running in a Linux VM is recommended

# Install via Homebrew
brew install podman

# Initialize and start the Podman machine (Linux VM)
podman machine init
podman machine start

# Verify
podman run hello-world

Known Limitations

• USB device forwarding is not currently supported natively
• Some specialized RF tools may have compatibility issues

Creating an Alias (Linux/macOS)

This part can be considered if you manually downloaded the binary.

For convenience, you can create an alias to run RF Swift from anywhere. If you didn’t use the install.sh script (which creates this automatically), you can add an alias manually:

echo "alias rfswift='$(pwd)/rfswift'" >> "$HOME/.$(basename $SHELL)rc"
source "$HOME/.$(basename $SHELL)rc"

Replace $(pwd)/rfswift with the full path to your RF Swift binary.

Next Steps

After installation, you can dive right into:

Troubleshooting

If you encounter issues during installation or usage:

1. Check the GitHub Issues page for known problems
2. Verify your container engine is working correctly:
   • Docker: docker run hello-world
   • Podman: podman run hello-world
3. Ensure you have the required permissions (e.g., user is in the docker group for Docker, or subuid/subgid configured for Podman)
4. Join our Discord community for direct assistance

Common Issues with the One-Line Installer

If you encounter issues with the one-line installer:

• Permission Denied: Ensure you have sudo privileges for Linux/macOS installation
• Docker/Podman Service Not Starting: Try restarting your system after installation
• Shell Alias Not Working: Open a new terminal window or manually source your shell configuration file
• GitHub API Rate Limiting: If you see an error about GitHub API limits, wait a few minutes and try again

Podman-Specific Issues

• “WARN[0000] “/” is not a shared mount”: Run sudo mount --make-rshared / or add it to /etc/fstab
• Device passthrough not working: Some devices may require --privileged or explicit --device flags; RF Swift handles this automatically in most cases
• Image pull fails with “short-name resolution”: Use the full image name, e.g., docker.io/penthertz/rfswift:sdr_light