Overview

CarbonFish is an Ansible-driven provisioning stack plus a FastAPI web CarbonFish Dashboard for managing sites, runtimes, services, firewall, databases, backups, and more on Debian/Ubuntu hosts running nginx.

Typical flow: bootstrap the control machine, install the LAMP-style stack (PHP-FPM, MariaDB, nginx), optionally Node.js and other components, then create user accounts with per-site PHP/Node versions, SSL, AWStats, and nginx vhosts—either interactively or from YAML.

In the repo

Quick start

From the repository root on a host that will run Ansible against your server (or localhost):

# 1. Install Ansible (and optionally Docker test prerequisites — see Testing)
./bootstrap.sh

# 2. Full stack: nginx, PHP versions, MariaDB, Node tooling, ModSecurity, etc.
./lamp.sh

# 3. Create accounts
./add-user.sh          # interactive single user
./bulk-user.sh         # multiple users from bulk-users.yml

# 4. Optional
./mysql57.sh           # MySQL 5.7 on a separate port
./harden.sh            # SSH / UFW hardening
./modsecurity-crs.sh   # ModSecurity CRS on existing install

Set CONFIG=/path/to/config.yml when scripts support it; inventory defaults to inventory.ini.

Features

  • PHP — multiple versions (e.g. 7.2–8.4), FPM pools, per-user selection
  • Node.js — NodeSource + NVM; versions 18 / 20 / 22 typical
  • Databases — MariaDB; optional MySQL 5.7; PostgreSQL install playbook
  • Scaling — RAM/CPU–aware tuning for MySQL and PHP-FPM
  • SSL — Let’s Encrypt via Certbot
  • Stats — AWStats with password protection
  • Toolbox — AWS CLI, Git, FFmpeg, ImageMagick, PM2, etc. (see LAMP role)

Configuration

Copy config.example.yml to config.yml. It drives playbooks (php_versions, default_php_version, ModSecurity, fail2ban, dashboard port, Docker test flags, etc.). Shell wrappers honor CONFIG=config.yml.

Bulk users

Copy bulk-users.example.yml to bulk-users.yml and list users: with new_user, server_name, SSH key, runtime, and versions. Run ./bulk-user.sh.

Provisioning & playbooks

Top-level playbooks are mirrored by bin/run-playbook-*.sh helpers (optional CONFIG, inventory.ini, pass-through "$@"). Examples:

  • bin/run-playbook-lamp.sh → lamp.yaml
  • bin/run-playbook-site.sh → site.yml
  • bin/run-playbook-php-manage.sh / nodejs-manage → PHP / Node management
  • bin/run-playbook-harden.sh, mysql57, postgresql-install
  • bin/run-playbook-modsecurity-crs.sh, repair-site-nginx, repair-all-nginx
  • bin/run-playbook-docker-install.sh — Docker Engine + Compose plugin (Debian/Ubuntu)
  • bin/setup-docker-for-tests.sh — optional engine install + test image build for CI/local tests

Use bin/rebuild.sh to chain common playbooks with flags (see script --help).

CarbonFish Dashboard

The dashboard is a FastAPI app (templates under dashboard/templates/) proxied behind nginx. It can run Ansible playbooks for provisioning and settings where permitted, manage services, UFW, PHP/Node/nginx/DB settings, backups, file manager, logs, and Cloud/AWS helpers—subject to server permissions.

Deployed service name is typically aligned with CarbonFish Dashboard / CarbonFish branding in systemd units. See the main README for screenshot references and operational notes.

Testing & Docker

Unit tests live under tests/; integration and Docker stack smoke tests use unittest and optional real Ansible / Docker. Docker baselines for PHP, nginx, and Node are under docker/.

Typical dev setup

  • install_docker_engine_for_tests: "yes" in config.yml (Debian/Ubuntu)
  • ./bin/setup-docker-for-tests.sh — installs Docker Engine then builds test images (containers stay stopped until tests)
  • ./run-tests.sh — starts stacks only for the integration pass, then tears them down per config
Read more

Security & WAF

  • Hardening — harden.yml / ./harden.sh: SSH, UFW, unattended upgrades, etc.
  • ModSecurity CRS — nginx + OWASP CRS; start in DetectionOnly, tune then move to On
  • Fail2ban — fail2ban_carbonfish jails for UFW blocks and nginx ModSecurity (Debian/Ubuntu + UFW)
  • Dashboard — UFW / Fail2ban tabs for listing jails, unban, whitelist merge files

Details and tables: see README.md (ModSecurity & Fail2ban sections).

Repository reference

This HTML guide stays short; the canonical long-form documentation remains in Markdown in the repo. Open these paths in your editor or viewer:

With the site document root set to website/, this page is website/docs/index.html (/docs/index.html on the host). Markdown and YAML links above resolve under website/repository/ (mirrors of the same files in the CarbonFish repo—refresh copies when those sources change).