From 070e03eafb6f9eee6ceb399a4208eebaf7da45c7 Mon Sep 17 00:00:00 2001
From: jfcheng <jianfeng.cheng@gmail.com>
Date: Sun, 22 Feb 2026 12:56:05 -0500
Subject: [PATCH] feat: Add Portracker service with Synology setup guides and
 scripts

---
 portracker/SETUP.md                     | 37 +++++++++++++++++++++++++
 portracker/create_portracker_folders.sh | 14 ++++++++++
 portracker/docker-compose.portainer.yml | 26 +++++++++++++++++
 3 files changed, 77 insertions(+)
 create mode 100644 portracker/SETUP.md
 create mode 100644 portracker/create_portracker_folders.sh
 create mode 100644 portracker/docker-compose.portainer.yml

diff --git a/portracker/SETUP.md b/portracker/SETUP.md
new file mode 100644
index 0000000..fac8cd5
--- /dev/null
+++ b/portracker/SETUP.md
@@ -0,0 +1,37 @@
+# Service Setup Guide: Portracker
+
+Portracker is a real-time port monitoring and service discovery tool.
+
+## 1. Pre-Setup (Manual)
+### Create Service User
+- [ ] **Manual**: Create a local user named `svc-portracker` in Synology DSM (Control Panel > User & Group).
+- [ ] **Manual**: Give this user read/write access to the `docker` shared folder.
+
+### Get User IDs
+- [ ] **Manual**: SSH into your NAS and run `id svc-portracker`.
+- [ ] **Action**: Record the `uid` (PUID) and `gid` (PGID) for use in Portainer.
+
+## 2. Infrastructure Setup
+### Run Setup Script
+- [ ] **Action**: Run the setup script to initialize the data directory:
+  ```bash
+  sudo bash create_portracker_folders.sh
+  ```
+- **What it does**: 
+  - Creates `/volume1/docker/portracker/data`.
+  - Sets ownership to the `svc-portracker` user (Note: You may need to edit the script with your specific PUID/PGID before running).
+
+## 3. Portainer Deployment
+### Environment Variables
+- [ ] **Action**: In the Portainer Stack configuration, add the following environment variables:
+  - `PUID=[Your UID]`
+  - `PGID=[Your GID]`
+  - `TZ=[Your Timezone, e.g., America/Toronto]`
+
+### Deploy Stack
+- [ ] **Action**: Create a new stack named `portracker`.
+- [ ] **Action**: Paste the content of `docker-compose.portainer.yml` and deploy.
+- [ ] **Verification**: Access the dashboard at `http://[NAS_IP]:4999`.
+
+> [!NOTE]
+> This service requires access to the Docker socket and host PID to monitor network services. It runs with elevated capabilities (`SYS_PTRACE`, `SYS_ADMIN`).
diff --git a/portracker/create_portracker_folders.sh b/portracker/create_portracker_folders.sh
new file mode 100644
index 0000000..b869247
--- /dev/null
+++ b/portracker/create_portracker_folders.sh
@@ -0,0 +1,14 @@
+#!/bin/bash
+# Define base path
+BASE="/volume1/docker/portracker"
+
+# Create folders
+mkdir -p "${BASE}/data"
+
+# Set ownership and permissions
+# IMPORTANT: Replace 1024:100 with your actual PUID:PGID if necessary
+# By default, we initialize it and you can adjust via Synology File Station if needed.
+chown -R 1024:100 "${BASE}"
+chmod -R 750 "${BASE}"
+
+echo "Folders created and permissions set for ${BASE}"
diff --git a/portracker/docker-compose.portainer.yml b/portracker/docker-compose.portainer.yml
new file mode 100644
index 0000000..0ba7aac
--- /dev/null
+++ b/portracker/docker-compose.portainer.yml
@@ -0,0 +1,26 @@
+services:
+  portracker:
+    image: mostafawahied/portracker:latest
+    container_name: Portracker
+    security_opt:
+      - apparmor:unconfined
+    pid: host
+    cap_add:
+      - SYS_PTRACE
+      - SYS_ADMIN
+    healthcheck:
+      test: ["CMD-SHELL", "nc -z 127.0.0.1 4999 || exit 1"]
+      interval: 10s
+      timeout: 5s
+      retries: 3
+      start_period: 90s
+    ports:
+      - 4999:4999
+    volumes:
+      - /volume1/docker/portracker/data:/data:rw
+      - /var/run/docker.sock:/var/run/docker.sock:ro
+    environment:
+      - PUID=${PUID:-1024}
+      - PGID=${PGID:-100}
+      - TZ=${TZ:-America/Toronto}
+    restart: on-failure:5