diff --git a/.dockerignore b/.dockerignore
index f692b8a1d3..2efc98f8fc 100644
--- a/.dockerignore
+++ b/.dockerignore
@@ -42,6 +42,7 @@ packages/backend/assets/instance.css
 animated.svg
 cliff.toml
 docker-compose.yml
+docker-compose.example.yml
 firefish.apache.conf
 firefish.nginx.conf
 flake.lock
diff --git a/.gitignore b/.gitignore
index 9c372235e7..00ab19930e 100644
--- a/.gitignore
+++ b/.gitignore
@@ -28,6 +28,7 @@ coverage
 !/.config/docker_ci.env
 !/.config/helm_values_example.yml
 !/.config/LICENSE
+docker-compose.yml
 
 # ESLint
 .eslintcache
diff --git a/docker-compose.yml b/docker-compose.example.yml
similarity index 100%
rename from docker-compose.yml
rename to docker-compose.example.yml
diff --git a/docs/docker.md b/docs/docker.md
index 11d2b87272..2b8667d1e1 100644
--- a/docs/docker.md
+++ b/docs/docker.md
@@ -5,18 +5,21 @@
 
 ## `docker-compose`
 
-There is a `docker-compose.yml` in the root of the project that you can use to build the container from source
+There are example config files that you can use to build the container from source
 
+- docker-compose.example.yml (**compose file**)
 - .config/docker_example.env (**db config settings**)
 - .config/default.yml (**firefish server settings**)
 
 ## Configuring
 
-Rename the files:
+Copy the files:
 
-`cp .config/example.yml .config/default.yml`
-
-`cp .config/docker_example.env .config/docker.env`
+```sh
+cp docker-compose.example.yml docker-compose.yml
+cp .config/example.yml .config/default.yml
+cp .config/docker_example.env .config/docker.env
+```
 
 then edit them according to your environment.
 You can configure `docker.env` with anything you like, but you will have to pay attention to the `default.yml` file:
@@ -37,12 +40,3 @@ Copy `docker-compose.yml` and the `config/` to a directory, then run the **docke
 NOTE: This will take some time to come fully online, even after download and extracting the container images, and it may emit some error messages before completing successfully. Specifically, the `db` container needs to initialize and so isn't available to the `web` container right away. Only once the `db` container comes online does the `web` container start building and initializing the firefish tables.
 
 Once the server is up you can use a web browser to access the web interface at `http://serverip:3000` (where `serverip` is the IP of the server you are running the firefish server on).
-
-## Docker for development
-
-```sh
-cd dev/
-docker-compose build
-docker-compose run --rm web pnpm run init
-docker-compose up -d
-```
diff --git a/docs/notice-for-admins.md b/docs/notice-for-admins.md
index 5814c89e94..d5744be47c 100644
--- a/docs/notice-for-admins.md
+++ b/docs/notice-for-admins.md
@@ -1,3 +1,29 @@
+# Unreleased
+
+## For Docker/Podman users
+
+- You only need to pull the new container image (`docker/podman pull`) to upgrade your server, so we assume that many of you don't update the code (`git pull --ff`), but it's still worth noting here that we have renamed `docker-compose.yml` to `docker-compose.example.yml` in the repository, and `docker-compose.yml` is now set to be untracked by git.
+    - Since `docker-compose.yml` may be edited by users (e.g., change port number, add reverse proxy), it shouldn't have been tracked by git in the first place.
+    - If you want to update the repository (`git pull --ff`), please take the following steps to keep your `docker-compose.yml`:
+        1. Backup (make a copy) your `docker-compose.yml`
+            ```sh
+            cp docker-compose.yml /tmp/my-docker-compose.yml
+            ```
+        2. Restore the original `docker-compose.yml` so it doesn't conflict with the upstream changes
+            ```sh
+            git checkout -- docker-compose.yml
+            ```
+        3. Pull the new code
+            ```sh
+            git switch main
+            git pull --ff
+            ```
+        4. Bring back your `docker-compose.yml`
+            ```sh
+            mv /tmp/my/docker-compose.yml docker-compose.yml
+            ```
+    - If any modifications are needed to `docker-compose.yml` in the future, we will provide a notice.
+
 # v20240214
 
 ## For systemd/pm2 users