All jobs

Add a Reverse Proxy to a Docker Compose Stack

Yes. An agent puts nginx in front of your Compose stack so the frontend and API share one port, keeps hot reload working, proves it with curl and opens a PR.

Run this on RushOpens the console with this prompt ready to send, in a Project that has your repository.

What the agent does

The agent clones the repository into its own cloud sandbox and reads the stack it is fronting before it writes a line of nginx config. In a Compose sample like react-express-mysql in docker/awesome-compose, compose.yaml runs three services: a backend built from backend/Dockerfile that publishes port 80 and the debugger ports 9229 and 9230, a frontend built with target: development that publishes 3000, and a db on MariaDB with the password mounted as a Compose secret. The backend and frontend sit on a public network and the backend and database on a private one. The frontend is a Create React App dev server whose src/setupProxy.js forwards /api to http://backend with the prefix stripped, and src/App.js fetches /api/ and shows the message the backend reads from SELECT VERSION(). The backend's Dockerfile has a HEALTHCHECK that runs healthcheck.js against /healthz, and the README tells the reader to open port 3000 and curl port 80.

The repository already shows how it likes a proxy done: nginx-golang-mysql/compose.yaml adds a proxy service on the nginx image with proxy/nginx.conf bind-mounted read-only over /etc/nginx/conf.d/default.conf and a single location / passing to the backend. The agent follows that shape and adds proxy/nginx.conf to the sample with two locations: /api/ passes to http://backend:80/, with the trailing slash so the prefix is stripped exactly as setupProxy.js does, and / passes to http://frontend:3000. Because the frontend is a dev server, the second location also sets proxy_http_version 1.1 and forwards the Upgrade and Connection headers, without which the hot-reload WebSocket fails and the browser console fills with reconnect errors.

In compose.yaml the new proxy service publishes port 80, joins the public network, and depends on the backend with condition: service_healthy, which the backend's existing Docker HEALTHCHECK makes meaningful, and on the frontend with service_started. The ports entries on frontend and backend are replaced with expose, so nothing but the proxy is reachable from the host, except the two debugger ports, which stay published because an editor attaches to them directly. setupProxy.js stays, since a developer running npm start outside Compose still needs it, and the README's instructions change from port 3000 and port 80 to a single http://localhost and curl localhost/api/.

Then it proves the stack. It runs docker compose up -d --build, waits for docker compose ps to show the backend healthy, curls localhost/api/ and checks the JSON message names the database version, curls localhost/ for the dev server's HTML, and reads docker compose logs proxy for the upgraded WebSocket request from the browser it opens in the sandbox. It confirms docker compose port frontend 3000 and docker compose port backend 80 are empty, so the old entry points are closed, and runs docker compose down -v so the sandbox leaves nothing behind.

Start it with one API call

POST https://api.phoenix.so/o/{org}/sessions with this body:

{
  "agent": "codex",
  "input": "Add an nginx reverse proxy to the react-express-mysql Compose sample. Read compose.yaml, backend/Dockerfile, backend/src/server.js, backend/healthcheck.js, frontend/Dockerfile, frontend/src/setupProxy.js, frontend/src/App.js, the sample README and nginx-golang-mysql/compose.yaml and its proxy/nginx.conf first. Add proxy/nginx.conf with location /api/ passing to http://backend:80/ so the prefix is stripped as setupProxy.js does, and location / passing to http://frontend:3000 with proxy_http_version 1.1 and the Upgrade and Connection headers so the dev server's hot-reload WebSocket works. Add a proxy service on the nginx image with the config bind-mounted read-only, publishing 80 on the public network, depending on backend with condition service_healthy and on frontend with service_started. Replace ports with expose on frontend and backend, keeping only the 9229 and 9230 debugger ports published. Update the README to one entry point. Run docker compose up -d --build, wait for the backend to be healthy, curl localhost/api/ and localhost/, confirm the old host ports are closed, check the proxy log for the WebSocket upgrade, run docker compose down -v, and open a pull request with the output.",
  "resources": [
    {
      "url": "https://github.com/your-org/your-app"
    }
  ]
}
  1. Get an API key. In the console, open Settings, then API keys, and create a key for your org. Send it in the Authorization header as a Bearer token.
  2. Send the request. POST the body in request.json to https://api.phoenix.so/o/{org}/sessions, with your repository as the resources URL. The run starts in its own cloud sandbox.
  3. Read what came back. Follow the run on its live stream or wait for the run.completed webhook, then read the result and its trajectory.

What comes back

What comes back is a pull request on its own branch adding react-express-mysql/proxy/nginx.conf, changing react-express-mysql/compose.yaml to add the proxy service and swap the frontend and backend ports for expose, and updating react-express-mysql/README.md so its project tree, Compose excerpt, expected docker ps output and curl example match. No file under backend/ or frontend/ changes, and setupProxy.js is left in place for runs outside Compose.

The description includes the docker compose ps table with the backend marked healthy, the curl localhost/api/ response, the proxy log line showing the WebSocket upgrade, and the empty docker compose port checks. The transcript at GET /o/{org}/sessions/{id}/messages keeps the build output and every command, so a reviewer can see the stack come up rather than read that it did.

Before merging, a reviewer checks that the /api/ location has its trailing slashes on both sides, that the Connection header is set to upgrade only for upgrade requests, and that the README no longer tells readers to open port 3000. A follow-up on the same session can add a TLS listener with a self-signed certificate or move the same pattern to another sample in the collection.

Run it on every Compose stack that publishes more than one port

A team that keeps several sample stacks runs this once per stack that still publishes its frontend and API separately. From your own server, send the body above to POST /o/{org}/sessions with the repository in resources, naming the sample directory in input, and a request_id that is a UUID v5 of the sample name so a retry is safe. Give the key a webhook_url and every run the key starts posts run.completed with data.session_url when its turn ends; a handler reads the pull request link from the session.

For a single stack, start the run from the console and follow it live, or label a Linear issue: an automation with a linear trigger on linear.issue.labeled, filtered to a label such as infra, starts one run per labelled issue with the issue text placed after the prompt.

The use case this job follows, with its automation and trigger: Hand off a long task.

Why run it on Rush?

A reverse proxy in front of a dev server is where small mistakes hide: a missing trailing slash that sends /api/api/ to the backend, a WebSocket that silently fails so hot reload stops, a depends_on that waits for a container rather than a healthy service. The agent brings the whole stack up in its own sandbox, with Docker and a browser available, and checks each of those with a command whose output it keeps.

The build, the health wait, the curls and the proxy log stay in the run's transcript, so the pull request's statement that the stack works behind one port is checkable line by line. Several samples can get the same change at once, each in its own sandbox and its own pull request, while the laptop that handed off the task stays free.

Frequently asked questions

Will hot reload still work through the proxy?

Yes, because the / location sets proxy_http_version 1.1 and forwards the Upgrade and Connection headers the dev server's WebSocket needs. The agent opens the site in the sandbox browser and reads the proxy log for the upgraded request, so the pull request shows it rather than assumes it.

Why keep setupProxy.js if nginx now routes /api?

Because a developer running npm start in frontend/ without Compose still needs the dev server to reach the backend. Inside Compose the browser's /api/ requests never reach the dev server's proxy, since nginx answers them first, so the file is harmless there and useful elsewhere.

Are the debugger ports still reachable?

Yes. Ports 9229 and 9230 on the backend stay published because an editor attaches to them from the host directly; only the HTTP ports move behind the proxy. If you want them closed too, say so in the prompt and the agent removes them with the others.

Does the proxy wait for the database?

Indirectly. The proxy depends on the backend being healthy, and the backend's HEALTHCHECK calls /healthz, which answers once the Express app is up. If you want the backend itself to wait for MariaDB, the depends_on with a database healthcheck from the nginx-golang-mysql sample is a follow-up on the same session.

More Docker Compose jobs

More jobs like this: Hand off a long task

Keep reading