Skip to content
Merged
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
24 changes: 12 additions & 12 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@

A Docker-based deployment system for containerized services, with optional extra application catalogs. No manual administration — every deploy is push-based, resolved and applied entirely from GitHub Actions. Built with Traefik reverse proxy and automatic SSL certificate management.

## 🎯 Key Features
## Key Features

- **Core Application Set** - Essential services for routing, auth, monitoring, automation, database access, error tracking, and analytics
- **Automatic SSL Certificates** - Cloudflare DNS and Let's Encrypt HTTP challenge support, routed through Traefik
Expand All @@ -12,15 +12,15 @@ A Docker-based deployment system for containerized services, with optional extra
- **Database Integration** - PostgreSQL, Redis, MongoDB, TimescaleDB pre-configured
- **Health Checks** - Built-in health monitoring for all services

## 📋 Target Server Requirements
## Target Server Requirements

A target server needs only:

- **Docker** >= 20.10
- **Docker Compose** >= 2.0
- SSH access for the deploy key configured in that target's `credentials`

## 🚀 Automated Deploy
## Automated Deploy

Deployment goes through [`deploy-shared.yml`](.github/workflows/deploy-shared.yml) (documented in the GitHub Actions section below), a reusable workflow wrapping [`deploy/deploy.py`](deploy/deploy.py) behind plain deploy vocabulary — `hosts`, `app-refs`, `apps`.

Expand All @@ -35,7 +35,7 @@ The deploy is push-based and runs entirely on the GitHub Actions runner:

What gets deployed — which app bundles, which apps actually run, and which encrypted env sources feed each one — is configured declaratively per target; see "Vaults And Targets" below for the manifest format.

## 📁 Project Structure
## Project Structure

```text
flightdeck/
Expand Down Expand Up @@ -77,7 +77,7 @@ flightdeck/
└── targets/ # Deployment targets
```

## 📦 Core Applications
## Core Applications

| Name | Purpose |
|------|---------|
Expand All @@ -93,7 +93,7 @@ flightdeck/

This catalog is itself published as its own release asset (`flightdeck-apps.zip`), merged at deploy time like any other entry in `app_refs`. Additional apps can live in any other repo's own `apps/`-shaped catalog, published the same way, and merged in by listing its ref alongside flightdeck's own.

## ⚙️ Configuration
## Configuration

### Environment Variables

Expand All @@ -116,7 +116,7 @@ To use the override for a given deploy, that app's own vault sets `MYAPP_SOME_PA

`traefik` and `databases` are created on the target host by `deploy/deploy.py` (derived from `apps/networks.yml`'s `external: true` entries); `internal` is created by Docker Compose itself.

## 🆕 Adding a New Application
## Adding a New Application

### Step 1: Create App Directory

Expand Down Expand Up @@ -156,7 +156,7 @@ services:

Add the app to whichever target's `apps` mapping should run it, and give it a vault declaring the env it needs (`MY_VALUE` in the example above) — see "Vaults And Targets" below. There is no local way to run an app outside of a real deploy; verify a new app definition by deploying it to a real (even if disposable) target.

## 🔍 Troubleshooting
## Troubleshooting

There's no manual administration path, so debugging means SSHing into the target host and using Docker Compose directly from the app's own folder — no wrapper needed, `apps/{app}/` is already a complete, ready-to-run Compose project:

Expand All @@ -173,12 +173,12 @@ A few things that don't fit that one-liner:
- **SSL**: `apps-data/traefik/acme.json` must exist and be `chmod 600`, or Traefik won't issue certificates.
- **DNS**: `nslookup app-name.domain.com` if the app resolves but isn't reachable.

## 📚 Additional Resources
## Additional Resources

- [AGENTS.md](AGENTS.md) - Technical documentation for AI agents and developers
- [RETIRED.md](RETIRED.md) - Apps removed from the active stack, and why

## 🔄 Similar Services
## Similar Services

Useful as a source of ready-made Docker Compose definitions when adding a new app to this catalog, or as a reference for how to structure one:

Expand All @@ -187,7 +187,7 @@ Useful as a source of ready-made Docker Compose definitions when adding a new ap
- [Coolify](https://coolify.io)
- [Portainer](https://www.portainer.io)

## ⚙️ GitHub Actions
## GitHub Actions

This repository provides four composite actions under `.github/actions/` (`build-bundle`, `build-apps-bundle`, `encrypt-env`, and `load-yaml-matrix`) and one reusable workflow, `deploy-shared.yml`.

Expand Down Expand Up @@ -362,6 +362,6 @@ jobs:

The `@v1.2.3` pin on the `uses:` line only controls which ref runs `deploy/deploy.py` itself. `app-refs` entries are separate and don't have to match the workflow pin. <!-- x-release-please-version -->

## 📝 License
## License

Flightdeck is released under the [MIT License](LICENSE).