From d4280d95b4ada32c474efdfb1d2c96f70934bfc4 Mon Sep 17 00:00:00 2001 From: Marcelo Soares Date: Tue, 18 Aug 2026 11:31:34 -0300 Subject: [PATCH 1/3] docs: Describe when serverpod start launches Docker Compose services --- .../01-server-fundamentals/02-running-your-server.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/06-concepts/01-server-fundamentals/02-running-your-server.md b/docs/06-concepts/01-server-fundamentals/02-running-your-server.md index 08117326..9d913bcd 100644 --- a/docs/06-concepts/01-server-fundamentals/02-running-your-server.md +++ b/docs/06-concepts/01-server-fundamentals/02-running-your-server.md @@ -56,7 +56,7 @@ serverpod start --no-flutter You can still launch an app on demand: press **Ctrl+R** in the terminal to open the app launch panel. -If your project runs auxiliary services from a `docker-compose.yaml`, such as Redis, pass `--docker` to start them with the session. +If your project has a `docker-compose.yaml` and its database is a Postgres on localhost without a [`dataPath`](../data-and-the-database/database/embedded-postgres), `serverpod start` starts the Compose services with the session. Otherwise it leaves them alone. Pass `--docker` or `--no-docker` to decide yourself. To run without the interactive terminal, pass `--no-tui`. When the output is not a terminal, for example in CI, `serverpod start` falls back to plain output on its own. From ead37a027438b04f993b97429c4ebdb4278ca6e2 Mon Sep 17 00:00:00 2001 From: Marcelo Soares Date: Thu, 20 Aug 2026 22:41:42 -0300 Subject: [PATCH 2/3] fix: Add the explanation to the migration guide and improve the wording --- .../01-server-fundamentals/02-running-your-server.md | 6 +++++- docs/11-upgrading/01-upgrade-to-four.md | 8 ++------ 2 files changed, 7 insertions(+), 7 deletions(-) diff --git a/docs/06-concepts/01-server-fundamentals/02-running-your-server.md b/docs/06-concepts/01-server-fundamentals/02-running-your-server.md index 9d913bcd..44286d37 100644 --- a/docs/06-concepts/01-server-fundamentals/02-running-your-server.md +++ b/docs/06-concepts/01-server-fundamentals/02-running-your-server.md @@ -56,7 +56,11 @@ serverpod start --no-flutter You can still launch an app on demand: press **Ctrl+R** in the terminal to open the app launch panel. -If your project has a `docker-compose.yaml` and its database is a Postgres on localhost without a [`dataPath`](../data-and-the-database/database/embedded-postgres), `serverpod start` starts the Compose services with the session. Otherwise it leaves them alone. Pass `--docker` or `--no-docker` to decide yourself. +If your project runs auxiliary services from a `docker-compose.yaml`, such as Redis, pass `--docker` to start them with the session. + +:::info +Passing the `--docker` flag is not needed if using PostgreSQL from a Docker Compose stack (no `dataPath` in the config). In such cases, `serverpod start` will automatically start and teardown the existing `docker-compose.yaml`, in case it was not already running. +::: To run without the interactive terminal, pass `--no-tui`. When the output is not a terminal, for example in CI, `serverpod start` falls back to plain output on its own. diff --git a/docs/11-upgrading/01-upgrade-to-four.md b/docs/11-upgrading/01-upgrade-to-four.md index 43cdcc5b..4ac80708 100644 --- a/docs/11-upgrading/01-upgrade-to-four.md +++ b/docs/11-upgrading/01-upgrade-to-four.md @@ -106,13 +106,9 @@ You have two paths. Pick the one that fits where you are today; both work with ` #### Keep your Docker Postgres (easiest upgrade) -If you've been developing against a Docker Postgres on 3.4, you can keep it without changing your config. Pass `--docker` to `serverpod start` so it uses your existing `docker-compose.yaml`: +If you've been developing against a Docker Postgres on 3.4, you can keep it without changing your config. -```bash -$ serverpod start --docker -``` - -With `--docker`, `serverpod start` brings up Docker if it isn't running, and tears down the compose stack on exit if the command brought it up. +On projects configured to use a regular PostgreSQL (no `dataPath` in the config), `serverpod start` brings up Docker if it isn't running, and tears down the compose stack on exit if the command brought it up. #### Switch to the embedded Postgres (recommended for new development) From 602438da22b79f2bbe58fc0b465470fce30108cd Mon Sep 17 00:00:00 2001 From: Marcelo Soares Date: Fri, 21 Aug 2026 14:31:37 -0300 Subject: [PATCH 3/3] docs: Address review on the Docker auto-start conditions --- .../01-server-fundamentals/02-running-your-server.md | 6 +----- docs/11-upgrading/01-upgrade-to-four.md | 2 +- 2 files changed, 2 insertions(+), 6 deletions(-) diff --git a/docs/06-concepts/01-server-fundamentals/02-running-your-server.md b/docs/06-concepts/01-server-fundamentals/02-running-your-server.md index 44286d37..34abb69d 100644 --- a/docs/06-concepts/01-server-fundamentals/02-running-your-server.md +++ b/docs/06-concepts/01-server-fundamentals/02-running-your-server.md @@ -56,11 +56,7 @@ serverpod start --no-flutter You can still launch an app on demand: press **Ctrl+R** in the terminal to open the app launch panel. -If your project runs auxiliary services from a `docker-compose.yaml`, such as Redis, pass `--docker` to start them with the session. - -:::info -Passing the `--docker` flag is not needed if using PostgreSQL from a Docker Compose stack (no `dataPath` in the config). In such cases, `serverpod start` will automatically start and teardown the existing `docker-compose.yaml`, in case it was not already running. -::: +If your project has a `docker-compose.yaml`, `serverpod start` brings it up automatically when your database is a Postgres on `localhost` with no `dataPath`, and tears it down on exit if it was the one that started it. When that does not apply, for example an embedded or remote database with Redis in Compose, pass `--docker` to start the stack anyway, or `--no-docker` to keep it off. To run without the interactive terminal, pass `--no-tui`. When the output is not a terminal, for example in CI, `serverpod start` falls back to plain output on its own. diff --git a/docs/11-upgrading/01-upgrade-to-four.md b/docs/11-upgrading/01-upgrade-to-four.md index 4ac80708..a56ce465 100644 --- a/docs/11-upgrading/01-upgrade-to-four.md +++ b/docs/11-upgrading/01-upgrade-to-four.md @@ -108,7 +108,7 @@ You have two paths. Pick the one that fits where you are today; both work with ` If you've been developing against a Docker Postgres on 3.4, you can keep it without changing your config. -On projects configured to use a regular PostgreSQL (no `dataPath` in the config), `serverpod start` brings up Docker if it isn't running, and tears down the compose stack on exit if the command brought it up. +On projects whose config points at a Postgres on `localhost` with no `dataPath`, `serverpod start` brings up the `docker-compose` stack if it isn't running, and tears it down on exit if the command brought it up. #### Switch to the embedded Postgres (recommended for new development)