Docker Compose Compatibility: The Journey Begins

Fresh Produce
1

Now that you can Use Containers with Flyctl (now with docs!), it’s time to take the next step—or rather, the first step on the next journey: Docker Compose compatibility.

Make no mistake: there are a number of things that Docker Compose can do that aren’t compatible with the Fly.io containers implementation, and vice versa. But the important thing is that the overlap between what the two can do is quite significant, and many of the differences can be mitigated.

Example motivations for this feature:

  • You have an existing application that runs with Docker Compose, and you want to deploy it to Fly.io.

  • You ran fly launch on a new application and it fails, and you want to debug it locally before trying again (divide and conquer).

  • You have an application deployed to Fly.io and want the ability to test out new features locally before deploying changes.

A quick demo to demonstrate the possibilities. Start by running:

fly version upgrade

Make sure that you are running v0.3.149 or later. Then, in an empty directory, run:

fly launch --from=https://github.com/fly-apps/rate-limiter-demo.git --ha=false

This will create an app that dumps out HTTP headers—nothing fancy.

Now edit the fly.toml and add:

[build]
compose = 'compose.yml'

Then change the internal port so that traffic is routed to the nginx container:

internal_port = 8080

Run fly deploy and refresh your browser rapidly. You will soon see:

503 Service Temporarily Unavailable

All without modifying a single line of your application. All that is required is a compose.yml and nginx.conf file, and you now have a two-container application that you can build and deploy.

This is just the beginning—there is much more work to be done. I would like that work to be based on real-world use cases, so let us know what you would like to see supported!

10 Likes
2

The perfect notification doesn’t exi-

4 Likes
3

flyctl v0.3.149 linux/amd64 Commit: 2c142c1141c084c54311d00923ae1c00be4d9407 BuildDate: 2025-07-03T18:18:47Z

Error: failed to fetch an image or build from source: app does not have a Dockerfile or buildpacks configured.

1 Like
4

Can you share your compose.yml file?

5

$ cat fly.toml
app = ‘testabc’
primary_region = ‘ams’

[build]
compose = ‘compose.yml’

[[vm]]
cpu_kind = ‘shared’
cpus = 1
memory_mb = 256

$ cat compose.yml
version: “3.8”

services:
nginx:
image: nginx:latest
ports:
- “8080:8080”
volumes:
- ./nginx.conf:/etc/nginx/conf.d/default.conf:ro
depends_on:
echo:
condition: service_healthy

echo:
build: .
healthcheck:
test: [“CMD”, “wget”, “-qO-”, “http://localhost:80”]

$ flyctl deploy
✓ Configuration is valid
→ Verified app config
==> Building image
==> Building image
Error: failed to fetch an image or build from source: app does not have a Dockerfile or buildpacks configured. See App configuration (fly.toml) · Fly Docs

1 Like
6

OK, so it looks like your fly.toml was built by hand (“memory_mb = 256”), which suggests you might not have cloned the rate limiter demo.

My directory looks like this:

% ls    
api-config.json	compose.yml	fly.toml	README.md
cli-config.json	Dockerfile	nginx.conf	server.js

You can omit the json and README files, but you will need the rest to be in place for this demo to work.

8

I’m proposing to change the fly.toml to (in most cases):

[build.compose]

Below that, one can specify the file, but in most cases that won’t be necessary: it will pick up the first of compose.yaml, compose.yml, docker-compose.yaml, or docker-compose.yml.

But the real reason for this change is to allow more options to be specified here. Examples:

  • Replacement of postgresql and redis with fly equivalents. Run locally with your own database, run in production with a managed database.
  • Allow fly secrets to override the definition in the compose file.
  • Update /etc/hosts to mimic docker compose network isolation. Everything runs on localhost on fly.io, and port number collisions are not likely, but service names are likely used in connection strings.
  • Exploit processes: run sidekiq on a separate machine
  • Volume mapping

These are just some ideas that need exploration and validating with real world use cases. But it seems obvious to me that some room for options is needed.

Next up after that will be modifying fly launch to auto detect compose files and set up a fly.toml with reasonable defaults as a starting point.

2 Likes
9

Nice, that is a good refinement idea, overall…

I think that making [build.compose], without any lines under it, be significant would put extra load on a weak point of TOML syntax, though.

Intuitively, empty stanzas do nothing—even though that’s not strictly what the semantic rules say.

(It’s the difference between {"build": {"compose": {}}} and {"build": {}} in JSON syntax.)

Maybe an explicit auto_detect_file = true, instead?

This would be really neat, :black_cat:.

(I worry about all those single-node Postgres instances out there…)

1 Like
10

That’s actually what I was going for. In JavaScript terms, I can test for:

if (c.build?.compose)

Or in my case (in go):

if c.Build != nil && c.Build.Compose != nil {

If it actually is a problem, I would rather make file required.

11

One problem though. I am using VSCode and the built-in schema autocomplete is faaaar old compared with the latest features. What’s at stake to have support for autocomplete in IDE? Is there any help the community can provide?