Flisk Byo

---
name: flisk-byo
description: Bring an existing service into a Flisk stack as a bring-your-own (BYO) resource with `flisk resource <name> --type bring-your-own` - from its own Dockerfile, a registry image, or a source tree elsewhere in the repo - including one-shot jobs such as migrations and seeders (`--restart no`). Use when you already have a Dockerfile, image or start command and want `flisk up` to run it. For a root docker-compose.yml use flisk-import-compose; for a Procfile use flisk-import-procfile; for new code use flisk-scaffold.
license: MIT
compatibility: Requires the flisk CLI. Does not deploy.
metadata:
  author: flisk-sh
  version: "1.0"
---

# Bring-your-own resources

A BYO resource is your container under Flisk's routing, health checks and stacks. Flisk generates the wiring, not the application code.

## Choose the path

- A root `docker-compose.yml` → `flisk import . --dry-run`, then `flisk import .` (the flisk-import-compose skill). It writes one BYO resource per Compose service.
- A Dockerfile or an image for one service → the workflow below.
- Only source and a start command → write a small Dockerfile that runs it, then the workflow below.
- A production Helm chart or Terraform → keep it for production and use BYO for the local loop (the flisk-helm skill).

## Workflow

1. Register it with the CLI (do not write `service.json` by hand; a hand-written one can be skipped by discovery):
   ```bash
   # from a Dockerfile, relative to the resource directory
   flisk resource legacy --type bring-your-own --stack shop \
     --dockerfile ./Dockerfile --health-path /health --path services/shop/legacy --yes

   # from an existing image, without a Traefik route
   flisk resource cache --type bring-your-own --stack shop --image redis:7-alpine --no-proxy --yes
   ```
2. To build from source elsewhere in the repo, set `"buildContext"` in the generated `service.json` (relative to the resource directory); `dockerfile` is then relative to that context.
3. Run `flisk doctor`, then `flisk up <stack>`, and check the URL from `flisk networks`.

## What the container must do

1. Listen on the `port` in `service.json`, read from `PORT`, and bind to `0.0.0.0`.
2. Answer HTTP 200 on `healthCheckPath` if it speaks HTTP. Non-HTTP services (databases, brokers) use `--no-proxy`.
3. Read `DATABASE_URL` from the environment if it uses the project Postgres.

## One-shot jobs

A BYO container restarts with `unless-stopped` by default, so a job that exits 0 would start again forever. Use `--restart no`:

```bash
flisk resource migrate --type bring-your-own --stack shop --dockerfile ./Dockerfile --restart no --yes
```

Add the job's dependency (`postgres`, or the migrator) to `dependsOn`. Ready-made jobs for Atlas, Dbmate, Drizzle, Prisma, TypeORM and others are in [examples/byo-jobs](https://github.com/flisk-sh/flisk/tree/main/examples/byo-jobs).

## Guardrails

- You own the Dockerfile and the health route. An existing Dockerfile is never overwritten.
- `--path` must stay inside the project; a `service.json` outside the project root is not supported.
- Resource names must be unique across the Flisk projects that share one Docker daemon.
- Do not hand-edit `.autogenerated/`. Change `service.json` and regenerate.
- Guide: [docs/byo.md](https://github.com/flisk-sh/flisk/blob/main/docs/byo.md).