From 9fed920ed11a80ea71cf1879ae9e57744e7bfb87 Mon Sep 17 00:00:00 2001
From: Nicolas De loof <nicolas.deloof@gmail.com>
Date: Tue, 29 Oct 2024 18:10:05 +0100
Subject: [PATCH] lifecycle hooks (#21061)

## Description

documentation for https://github.com/docker/compose/pull/12166

## Related issues or tickets

[<!-- Related issues, pull requests, or Jira tickets
-->](https://docker.atlassian.net/browse/COMP-760)

## Reviews

- [ ] Technical review
- [ ] Editorial review
- [ ] Product review

Signed-off-by: Nicolas De Loof <nicolas.deloof@gmail.com>
---
 content/manuals/compose/how-tos/lifecycle.md | 65 ++++++++++++++++++++
 1 file changed, 65 insertions(+)
 create mode 100644 content/manuals/compose/how-tos/lifecycle.md

diff --git a/content/manuals/compose/how-tos/lifecycle.md b/content/manuals/compose/how-tos/lifecycle.md
new file mode 100644
index 0000000000..aa332877e9
--- /dev/null
+++ b/content/manuals/compose/how-tos/lifecycle.md
@@ -0,0 +1,65 @@
+---
+title: Using lifecycle hooks with Compose
+linkTitle: Use lifecycle hooks
+weight: 20
+desription: How to use lifecycle hooks with Docker Compose
+keywords: cli, compose, lifecycle, hooks reference
+---
+
+## Services lifecycle hooks
+
+When Docker Compose runs a container, it uses two elements, 
+[ENTRYPOINT and COMMAND](https://github.com/manuals//engine/containers/run.md#default-command-and-options), 
+to manage what happens when the container starts and stops.
+
+However, it can sometimes be easier to handle these tasks separately with lifecycle hooks - 
+commands that run right after the container starts or just before it stops.
+
+Lifecycle hooks are particularly useful because they can have special privileges 
+(like running as the root user), even when the container itself runs with lower privileges 
+for security. This means that certain tasks requiring higher permissions can be done without 
+compromising the overall security of the container.
+
+### Post-start hooks
+
+Post-start hooks are commands that run after the container has started, but there's no 
+set time for when exactly they will execute. The hook execution timing is not assured during 
+the execution of the container's `entrypoint`.
+
+In the example provided:
+
+- The hook is used to change the ownership of a volume to a non-root user (because volumes 
+are created with root ownership by default).
+- After the container starts, the `chown` command changes the ownership of the `/data` directory to user `1001`.
+
+```yaml
+services:
+  app:
+    image: backend
+    user: 1001
+    volumes:
+      - data:/data    
+    post_start:
+      - command: chown -R /data 1001:1001
+        user: root
+
+volumes:
+  data: {} # a Docker volume is created with root ownership
+```
+
+### Pre-stop hooks
+
+Pre-stop hooks are commands that run before the container is stopped by a specific 
+command (like `docker compose down` or stopping it manually with `Ctrl+C`). 
+These hooks won't run if the container stops by itself or gets killed suddenly.
+
+In the following example, before the container stops, the `./data_flush.sh` script is 
+run to perform any necessary cleanup.
+
+```yaml
+services:
+  app:
+    image: backend
+    pre_stop:
+      - command: ./data_flush.sh
+```