Forail DevOps

Deployment, infrastructure, and CI/CD for the Forail platform.

Overview

This repo contains everything needed to deploy the Forail platform:

• Docker Compose configuration (production + development)
• Nginx reverse proxy
• SSL/TLS (Let's Encrypt)
• Backup/restore scripts
• CI/CD pipeline configuration
• Health check scripts
• Receptor mesh configuration

Quick Start

# 1. Clone the repo
git clone https://github.com/forail-platform/forail-devops.git
cd forail-devops

# 2. Configure environment
cp .env.example .env
# Set the four `changeme` values in .env -- the stack will not come up without
# them. The rest has working defaults.

# 3. Start
docker compose up -d

# 4. Check health
docker compose ps          # every service should report (healthy)

The UI is then on https://localhost; http:// redirects to it. Log in with FORAIL_ADMIN_USER / FORAIL_ADMIN_PASSWORD from your .env.

On first start, when nginx/ssl/ is empty, a self-signed certificate is generated so nginx has something to serve — your browser will warn about it. Drop a real certificate into nginx/ssl/ and it is left alone; see README-prod.md.

Running jobs

The stack above serves the API and the UI, but it cannot execute anything — projects will not sync and every job stays in pending. Job execution runs playbooks through podman inside the task container, which needs cgroup, mount and user-namespace privileges:

FORAIL_TASK_PRIVILEGED=true FORAIL_TASK_CGROUP=host docker compose up -d

This is off by default on purpose: a privileged container is a trivial escape to host root. Turn it on only on a host you are willing to treat as a dedicated job runner. This is tracked as H4 in the security notes.

The scripts under scripts/ are the container health probes — Compose mounts them into the containers and runs them there (bash /etc/forail/healthcheck-web.sh), so they call forail-manage and only work inside the image. Run one by hand with:

docker compose exec forail-web bash /etc/forail/healthcheck-web.sh && echo healthy

Architecture

┌──────────────┐     ┌───────────────┐
│ forail-backend│     │ forail-frontend│
│   (Django)   │     │   (React)     │
└──────┬───────┘     └──────┬────────┘
       │                     │
       ▼                     ▼
┌─────────────────────────────────────┐
│          Docker Registry            │
└─────────────────┬───────────────────┘
                  │
                  ▼
       ┌─────────────────┐
       │   forail-devops   │
       │ docker-compose   │
       └────────┬────────┘
                │
    ┌───────────┼───────────┐
    ▼           ▼           ▼
┌────────┐ ┌────────┐ ┌────────┐
│ nginx  │ │postgres│ │ redis  │
└────────┘ └────────┘ └────────┘

Services

Service	Image	Port	Description
nginx	nginx:latest	443, 80	Reverse proxy, SSL termination
forail-web	ghcr.io/forail-platform/forail-backend	8013	Django API + uWSGI
forail-task	ghcr.io/forail-platform/forail-backend	-	Celery worker + Dispatcher
postgres	postgres:15	5432	Database
redis	redis:7	6379	Cache + message broker

Structure

forail-devops/
├── docker-compose.yml       # Production stack
├── docker-compose.dev.yml   # Development stack
├── docker/                  # Dockerfile templates
├── nginx/                   # Nginx configuration + SSL
├── receptor/                # Receptor mesh configuration
├── scripts/                 # Backup, restore, health checks
├── settings/                # Django production settings
├── .env.example             # Environment template
└── .github/workflows/       # GitHub Actions CI/CD

Documentation

Published on the developer and user docs site — the markdown sources are kept outside this repository:

• Architecture Overview
• Docker Deployment
• CI/CD Pipeline
• Contributing Guide
• User Handbook
• Administrator Handbook

Release

• Release notes — one page per release

Backup & Restore

# Backup (writes to the forail_backups volume)
docker compose exec -T forail-task bash /etc/forail/backup.sh

# Restore: stop the writers, restore in a one-off container, start again
docker compose stop forail-web forail-task
docker compose run --rm --no-deps forail-task bash /etc/forail/restore.sh --yes
docker compose up -d

Keep .env -- at least FORAIL_SECRET_KEY -- with your backups: without it, a restored database cannot decrypt any stored credential. Details, upgrade and rollback: the Administrator Handbook.

Related Repositories

• forail-backend — Django API + Task Engine
• forail-frontend — React UI

Project History

The Forail platform is a modernized fork of Ansible AWX, licensed under the Apache License 2.0. See forail-backend/NOTICE for full attribution.

License

Licensed under the Apache License, Version 2.0. See LICENSE.