diff --git a/.env.sample b/.env.sample
new file mode 100644
index 0000000..a41b065
--- /dev/null
+++ b/.env.sample
@@ -0,0 +1,2 @@
+BASEDIR=
+INTRANET=
\ No newline at end of file
diff --git a/README.md b/README.md
index 8b35c22..54da200 100644
--- a/README.md
+++ b/README.md
@@ -1,3 +1,52 @@
-# compose-homepage
+# Homepage Dashboard
+* can be run on single node setup or in swarm  
 
-Homepage Dashboard
\ No newline at end of file
+## howto
+### single node
+#### start container
+```bash
+docker compose up -d
+```
+
+#### stop container (and remove)
+```bash
+docker compose down
+```
+
+#### view logs
+```bash
+docker compose logs -f
+```
+
+#### reload config
+```bash
+docker compose restart
+```
+
+### swarm
+#### start aka deploy
+hint: drone fails to start until git auth source is created and set in vars
+```bash
+docker stack deploy -c docker-compose.yml homepage
+```
+
+#### stop container aka service
+```bash
+docker stack rm homepage
+```
+
+#### view logs
+```bash
+docker service logs homepage -f
+```
+
+#### reload config (no downtime if replica 2 or more)
+```bash
+docker service update hoempage --force
+```
+
+## example caddy config
+```
+git.example.com {
+    reverse_proxy homepage:3000
+}
\ No newline at end of file
diff --git a/docker-compose.yml b/docker-compose.yml
new file mode 100644
index 0000000..acb892c
--- /dev/null
+++ b/docker-compose.yml
@@ -0,0 +1,26 @@
+services:
+  homepage:
+    image: ghcr.io/gethomepage/homepage:latest
+    container_name: homepage
+    restart: unless-stopped
+    env_file: 
+      - .env
+    ports:
+      - 3000:3000
+    deploy:
+      replicas: 1
+      placement:
+        max_replicas_per_node: 1
+      update_config:
+        parallelism: 1
+        delay: 10s
+    volumes:
+      - ${basepath:-.}/files:/app/config
+      - /var/run/docker.sock:/var/run/docker.sock # (optional) For docker integrations
+    networks:
+      - backend
+
+networks:
+  backend:
+    name: ${INTRANET:-backend}
+    external: true
\ No newline at end of file