Ansible Installation

Deploy FluffBuzz to production servers with fluffbuzz-ansible — an automated installer with security-first architecture.

The fluffbuzz-ansible repo is the source of truth for Ansible deployment. This page is a quick overview.

Prerequisites

Requirement	Details
OS	Debian 11+ or Ubuntu 20.04+
Access	Root or sudo privileges
Network	Internet connection for package installation
Ansible	2.14+ (installed automatically by the quick-start script)

What You Get

Firewall-first security — UFW + Docker isolation (only SSH + Tailscale accessible)
Tailscale VPN — secure remote access without exposing services publicly
Docker — isolated sandbox containers, localhost-only bindings
Defense in depth — 4-layer security architecture
Systemd integration — auto-start on boot with hardening
One-command setup — complete deployment in minutes

Quick Start

One-command install:

curl -fsSL https://raw.githubusercontent.com/fluffbuzz/fluffbuzz-ansible/main/install.sh | bash

What Gets Installed

The Ansible playbook installs and configures:

Tailscale — mesh VPN for secure remote access
UFW firewall — SSH + Tailscale ports only
Docker CE + Compose V2 — for the default agent sandbox backend
Node.js 24 + pnpm — runtime dependencies (Node 22 LTS, currently 22.14+, remains supported)
FluffBuzz — host-based, not containerized
Systemd service — auto-start with security hardening

The gateway runs directly on the host (not in Docker). Agent sandboxing is optional; this playbook installs Docker because it is the default sandbox backend. See Sandboxing for details and other backends.

Post-Install Setup

Switch to the fluffbuzz user

sudo -i -u fluffbuzz

Run the onboarding wizard

The post-install script guides you through configuring FluffBuzz settings.

Connect messaging providers

fluffbuzz channels login

Verify the installation

sudo systemctl status fluffbuzz
sudo journalctl -u fluffbuzz -f

Connect to Tailscale

Join your VPN mesh for secure remote access.

Quick Commands

# Check service status
sudo systemctl status fluffbuzz

# View live logs
sudo journalctl -u fluffbuzz -f

# Restart gateway
sudo systemctl restart fluffbuzz

# Provider login (run as fluffbuzz user)
sudo -i -u fluffbuzz
fluffbuzz channels login

Security Architecture

The deployment uses a 4-layer defense model:

Firewall (UFW) — only SSH (22) + Tailscale (41641/udp) exposed publicly
VPN (Tailscale) — gateway accessible only via VPN mesh
Docker isolation — DOCKER-USER iptables chain prevents external port exposure
Systemd hardening — NoNewPrivileges, PrivateTmp, unprivileged user

To verify your external attack surface:

nmap -p- YOUR_SERVER_IP

Only port 22 (SSH) should be open. All other services (gateway, Docker) are locked down. Docker is installed for agent sandboxes (isolated tool execution), not for running the gateway itself. See Multi-Agent Sandbox and Tools for sandbox configuration.

Manual Installation

If you prefer manual control over the automation:

Install prerequisites

sudo apt update && sudo apt install -y ansible git

Clone the repository

git clone https://github.com/fluffbuzz/fluffbuzz-ansible.git
cd fluffbuzz-ansible

Install Ansible collections

ansible-galaxy collection install -r requirements.yml

Run the playbook

./run-playbook.sh

Alternatively, run directly and then manually execute the setup script afterward:

ansible-playbook playbook.yml --ask-become-pass
# Then run: /tmp/fluffbuzz-setup.sh

Updating

The Ansible installer sets up FluffBuzz for manual updates. See Updating for the standard update flow. To re-run the Ansible playbook (for example, for configuration changes):

cd fluffbuzz-ansible
./run-playbook.sh

This is idempotent and safe to run multiple times.

Troubleshooting

Firewall blocks my connection

Ensure you can access via Tailscale VPN first
SSH access (port 22) is always allowed
The gateway is only accessible via Tailscale by design

Service will not start

# Check logs
sudo journalctl -u fluffbuzz -n 100

# Verify permissions
sudo ls -la /opt/fluffbuzz

# Test manual start
sudo -i -u fluffbuzz
cd ~/fluffbuzz
fluffbuzz gateway run

Docker sandbox issues

# Verify Docker is running
sudo systemctl status docker

# Check sandbox image
sudo docker images | grep fluffbuzz-sandbox

# Build sandbox image if missing
cd /opt/fluffbuzz/fluffbuzz
sudo -u fluffbuzz ./scripts/sandbox-setup.sh

Advanced Configuration

For detailed security architecture and troubleshooting, see the fluffbuzz-ansible repo:

fluffbuzz-ansible — full deployment guide
Docker — containerized gateway setup
Sandboxing — agent sandbox configuration
Multi-Agent Sandbox and Tools — per-agent isolation

Install overview

Containers

Hosting

Maintenance

Ansible

Ansible Installation

Prerequisites

What You Get

Quick Start

What Gets Installed

Post-Install Setup

Quick Commands

Security Architecture

Manual Installation

Updating

Troubleshooting

Advanced Configuration

​Ansible Installation

​Prerequisites

​What You Get

​Quick Start

​What Gets Installed

​Post-Install Setup

​Quick Commands

​Security Architecture

​Manual Installation

​Updating

​Troubleshooting

​Advanced Configuration

​Related

Ansible Installation

Prerequisites

What You Get

Quick Start

What Gets Installed

Post-Install Setup

Quick Commands

Security Architecture

Manual Installation

Updating

Troubleshooting

Advanced Configuration

Related