# Coolify Build Fixer

`fix-coolify-builds` is a Codex skill for evidence-led diagnosis, repair, and verification of Docker builds, Docker Compose deployments, Coolify resources, Traefik routing, GitHub CI, and container restart loops.

It is designed around a Coolify installation whose designated public Docker network is `coolify`. It supports both Coolify-managed deployments and explicitly self-managed Raw Compose deployments without applying the wrong networking pattern to either mode.

## What the skill does

- Inspects Dockerfiles, Compose files, build logs, runtime state, healthchecks, and Traefik labels.
- Uses GitHub repository, pull request, and CI context when the GitHub integration is available.
- Uses the Coolify MCP server for read-only infrastructure discovery.
- Distinguishes build failures, startup crashes, healthcheck failures, Docker restarts, PM2 worker restarts, Coolify redeployments, routing problems, and TLS/DNS failures.
- Handles `Stopped after reaching restart limit` incidents, including cases where Coolify already removed the crashed container.
- Validates the `coolify` public-network contract for managed and Raw Compose deployments.
- Proposes the smallest reversible fix and verifies each layer from build to external request.

The skill never stores Coolify tokens and does not perform production restarts, deployments, pushes, or destructive Docker operations without explicit authorization.

## Repository layout

```text
fix-coolify-builds/
├── SKILL.md
├── README.md
├── SOURCE.md
├── agents/
│   └── openai.yaml
├── references/
│   ├── diagnostic-playbook.md
│   ├── network-and-routing.md
│   ├── official-sources.md
│   └── restart-loops.md
├── scripts/
│   └── compose_preflight.py
└── tests/
    └── test_compose_preflight.py
```

`SKILL.md` contains the core workflow. Codex loads the reference files only when the current incident requires them. `compose_preflight.py` performs deterministic, read-only checks against a resolved Compose model.

## Requirements

- A current Codex CLI, IDE extension, or ChatGPT desktop app with skill support.
- Docker Compose when running the bundled Compose preflight against a YAML file.
- Access to the relevant GitHub repositories through the GitHub plugin/connector or an authenticated `gh` CLI fallback.
- Optional but recommended: the Coolify MCP endpoint enabled on the target Coolify instance.
- Permission to inspect the Docker host when runtime-level evidence is required.

## Install the skill

Codex discovers skills from several locations. Use either the user-scoped or repository-scoped installation below.

### Option 1: User-scoped installation

Install once for all repositories:

```bash
git clone https://github.com/mleem97/mm-skills.git
mkdir -p "$HOME/.agents/skills"
ln -s "$(pwd)/mm-skills/fix-coolify-builds" \
  "$HOME/.agents/skills/fix-coolify-builds"
```

Instead of a symlink, you may copy the folder:

```bash
mkdir -p "$HOME/.agents/skills"
cp -R mm-skills/fix-coolify-builds \
  "$HOME/.agents/skills/fix-coolify-builds"
```

### Option 2: Repository-scoped installation

Make the skill available only inside one repository:

```bash
mkdir -p /path/to/project/.agents/skills
cp -R fix-coolify-builds \
  /path/to/project/.agents/skills/fix-coolify-builds
```

Codex scans `.agents/skills` from the current working directory up to the repository root. It normally detects changes automatically; restart the Codex client if the skill does not appear.

In Codex CLI or the IDE extension, run `/skills` or type `$fix-coolify-builds` to verify discovery.

> Hosted ChatGPT Work does not install a skill merely because its files exist in a GitHub repository. Use the workspace skill/plugin installation flow there. The GitHub folder is the source distribution for Codex-local and repository-scoped installation.

For the current official skill locations and behavior, see [Build skills](https://learn.chatgpt.com/docs/build-skills).

## Configure the Coolify MCP server

Coolify's built-in MCP server is currently read-only and uses Streamable HTTP with bearer-token authentication.

### 1. Enable MCP in Coolify

1. Enable API access on the Coolify instance.
2. Open **Settings → Advanced**.
3. Enable **MCP Server**.
4. Create a Coolify API token with `read` permission only.
5. Keep the token in a local secret store or environment variable. Never commit it.

The configured endpoint for this skill is:

```text
https://panel.meyermedia.eu/mcp
```

See the [Coolify MCP documentation](https://coolify.io/docs/integrations/mcp) for server-side setup.

### 2. Add the MCP server to Codex

The ChatGPT desktop app and Codex IDE extension provide **Settings → MCP servers → Add server**. Choose **Streamable HTTP**, enter the endpoint above, save it, and restart the client.

For Codex CLI or advanced configuration, add this to `~/.codex/config.toml` or a trusted repository's `.codex/config.toml`:

```toml
[mcp_servers.coolify-meyermedia]
url = "https://panel.meyermedia.eu/mcp"
bearer_token_env_var = "COOLIFY_MCP_TOKEN"
required = false
default_tools_approval_mode = "writes"
```

Provide `COOLIFY_MCP_TOKEN` through your operating system, shell environment, or secret manager. Do not put the token directly in `config.toml`.

Verify the connection with:

```bash
codex mcp list
```

Inside Codex, use `/mcp` to inspect connected servers. For current MCP configuration options, see the [Codex MCP documentation](https://learn.chatgpt.com/docs/extend/mcp).

## Configure GitHub access

### ChatGPT Work or desktop app

1. Install and authorize the GitHub plugin/connector.
2. Grant it access to the repositories the skill should inspect or repair.
3. Confirm that repository files, pull requests, and workflow metadata are visible.

The skill prefers the GitHub connector for structured repository and PR context. Detailed GitHub Actions logs may use the local `gh` CLI when connector coverage is insufficient.

### Local CLI fallback

Install and authenticate GitHub CLI:

```bash
gh auth login
gh auth status
```

Do not grant broader repository permissions than the intended repair workflow needs.

## Use the skill

Invoke it explicitly:

```text
$fix-coolify-builds Diagnose why this Coolify deployment keeps restarting and propose the smallest safe fix.
```

Other examples:

```text
$fix-coolify-builds Analyze this Docker build log and fix the failing stage.

$fix-coolify-builds Investigate a Traefik 504 for this Coolify Compose application. The public network is coolify.

$fix-coolify-builds Diagnose "Stopped after reaching restart limit (10/10)" and distinguish Docker, PM2, and redeployment loops.

$fix-coolify-builds Inspect the failing GitHub Actions job, patch the repository, and verify the Docker build. Do not push until I approve.
```

Codex may also invoke the skill implicitly when a request matches the trigger description in `SKILL.md`.

## Run the Compose preflight

For a Coolify-managed application or Docker Compose build pack:

```bash
python3 scripts/compose_preflight.py compose.yaml --mode managed
```

For Raw Compose or an explicitly self-managed stack:

```bash
python3 scripts/compose_preflight.py compose.yaml \
  --mode raw \
  --public-network coolify
```

The script runs `docker compose config --format json` and checks the resolved model. It does not modify Docker state or the Compose file.

Exit behavior:

- `0`: no errors; warnings are allowed unless `--strict` is used.
- `1`: warnings exist and `--strict` was selected.
- `2`: configuration or policy errors were found.

For CI-friendly JSON output:

```bash
python3 scripts/compose_preflight.py compose.yaml \
  --mode raw \
  --public-network coolify \
  --output json
```

Run the bundled unit tests with:

```bash
python3 -m unittest discover -s tests -v
```

## Public-network policy

The word `coolify` means the designated public destination/network, but the correct configuration depends on deployment mode:

- **Coolify-managed application or Compose build pack:** select the Coolify Destination whose Docker network is `coolify`. Do not add a repository-defined custom network merely to reach Traefik.
- **Raw or explicitly self-managed Compose:** reference the existing network with `external: true` and `name: coolify`. Attach only public services. If a routed container has multiple networks, set `traefik.docker.network=coolify`.
- Keep databases and caches on private networks unless cross-stack connectivity is intentionally required.

See [`references/network-and-routing.md`](./references/network-and-routing.md) before changing routing or network configuration.

## Restart-loop workflow

For `Stopped after reaching restart limit`, the skill:

1. Distinguishes the Coolify project UUID from the deployed resource UUID.
2. Searches by `com.docker.compose.project` and `com.docker.compose.service` instead of a generated container name.
3. Handles the case where Coolify already stopped or removed the crashed container.
4. Captures the first controlled restart after explicit approval.
5. Separates Docker restarts from PM2 worker restarts and new Coolify deployments.
6. Interprets exit codes, `OOMKilled`, migrations, missing runtime files, and healthcheck evidence.

See [`references/restart-loops.md`](./references/restart-loops.md) for the complete playbook.

## Safety model

- Coolify MCP is used read-only.
- Tokens, credentials, database URLs, private keys, and secret-bearing logs must be redacted.
- Repository edits may be prepared when a fix is requested.
- Commit, push, pull request, restart, redeployment, proxy changes, and live-server mutations require explicit authorization.
- Destructive Docker operations, volume deletion, broad permission changes, and disabling restart protection are not diagnostic shortcuts.
- The skill verifies installed versions and current primary documentation rather than assuming a fixed Docker, Coolify, or Traefik release.

## Troubleshooting setup

### The skill is not listed

- Confirm that `SKILL.md` exists directly inside the installed `fix-coolify-builds` folder.
- Confirm the folder is under `$HOME/.agents/skills` or the repository's `.agents/skills` path.
- Run `/skills` and restart the Codex client if discovery has not refreshed.

### Coolify MCP returns 401

- Confirm the token is still valid.
- Confirm `COOLIFY_MCP_TOKEN` is visible to the Codex process.
- Use a Coolify token with `read` permission.
- Revoke and replace an exposed token immediately.

### Coolify MCP returns 404

- Confirm MCP is enabled under Coolify **Settings → Advanced**.
- Confirm the endpoint is exactly `https://panel.meyermedia.eu/mcp`.
- Confirm a proxy or access-control layer is not rewriting the MCP path.

### GitHub content is unavailable

- Confirm the GitHub plugin/connector is authorized for the repository.
- For CLI fallback, run `gh auth status`.
- Check organization or private-repository access restrictions.

### Docker commands find no crashed container

Coolify may have removed it after enforcing the restart limit. Use the resource UUID and stable Compose labels, then perform one controlled restart capture only after approval. See the restart-loop reference for the exact workflow.

## Updating

If installed through a symlink, update the clone:

```bash
git -C mm-skills pull --ff-only
```

If installed by copying the folder, pull the repository and replace the installed copy with the updated `fix-coolify-builds` directory.

## Further reading

- [Official Codex skill documentation](https://learn.chatgpt.com/docs/build-skills)
- [Official Codex MCP documentation](https://learn.chatgpt.com/docs/extend/mcp)
- [Coolify documentation](https://coolify.io/docs/)
- [Coolify MCP documentation](https://coolify.io/docs/integrations/mcp)
- [Docker documentation](https://docs.docker.com/)
- [Traefik documentation](https://doc.traefik.io/traefik/)