From 1a2c006965af393b90e6d94e49814482b264ae78 Mon Sep 17 00:00:00 2001
From: traveler <traveler@wasted-bandwidth.net>
Date: Fri, 1 May 2026 13:44:14 -0500
Subject: [PATCH] docs(gremlin): create vscode

---
 Netgrimoire/Services/vscode/vscode.md | 111 ++++++++++++++++++++++++++
 1 file changed, 111 insertions(+)
 create mode 100644 Netgrimoire/Services/vscode/vscode.md

diff --git a/Netgrimoire/Services/vscode/vscode.md b/Netgrimoire/Services/vscode/vscode.md
new file mode 100644
index 0000000..0e55bbe
--- /dev/null
+++ b/Netgrimoire/Services/vscode/vscode.md
@@ -0,0 +1,111 @@
+# vscode
+
+## Overview
+This Stack provides a Docker Swarm-based installation of Code Server, a lightweight, self-hosted version control server for Git repositories.
+
+---
+
+## Architecture
+| Service | Image | Port | Role |
+|---------|-------|------|------|
+- **Host:** docker4
+- **Network:** netgrimoire
+- **Exposed via:** code.netgrimoire.com, Internal only
+- **Homepage group:** Development
+
+---
+### Build & Configuration
+
+#### Prerequisites
+No specific prerequisites for this stack.
+
+#### Volume Setup
+```bash
+mkdir -p /DockerVol/code/config
+chown -R code:code /DockerVol/code/
+```
+
+#### Environment Variables
+```bash
+# generate: openssl rand -hex 32
+PUID=1964
+PGID=1964
+SUDO_PASSWORD=F@lcon13
+PROXY_DOMAIN=code.netgrimoire.com
+TZ=America/Chicago
+```
+
+#### Deploy
+```bash
+cd services/swarm/stack/vscode
+set -a && source .env && set +a
+docker stack config --compose-file vscode-stack.yml > resolved.yml
+docker stack deploy --compose-file resolved.yml vscode
+rm resolved.yml
+docker stack services vscode
+```
+
+#### First Run
+This process is automatically handled by the Docker Swarm deployment.
+
+---
+### User Guide
+
+#### Accessing vscode
+| Service | URL | Purpose |
+- **Host:** code.netgrimoire.com:8443
+- Internal only
+
+#### Primary Use Cases
+To access and contribute to your Git repositories, simply navigate to the Code Server interface via the provided URL. For detailed instructions, refer to the official [Code Server documentation](https://code-server.org/).
+
+#### NetGrimoire Integrations
+This Stack integrates with other services in NetGrimoire through environment variables and labels:
+- Caddy reverse proxy: caddy-docker-proxy:code.netgrimoire.com
+- Kuma monitoring: kuma.cs.http.name:Code Server, kuma.cs.http.url:http://code-server:8443
+- Diun image update monitoring: enabled
+
+---
+### Operations
+
+#### Monitoring
+```bash
+docker stack services vscode
+docker service logs vscode -f
+```
+
+#### Backups
+Critical vs. reconstructable paths:
+- Critical: /DockerVol/code/data
+- Reconstructable: /DockerVol/code/config
+
+#### Restore
+```bash
+cd services/swarm/stack/vscode
+./deploy.sh
+```
+
+---
+### Common Failures
+
+| Symptom | Cause | Fix |
+|---------|-------|-----|
+| Code Server does not start on docker4 | Incorrect PUID/PGID or SUDO_PASSWORD | Verify that these environment variables are set correctly in .env. |
+| Connection issues with caddy reverse proxy | Invalid CADDY_PORT or proxy configuration in .env | Check the CADDY_PORT value and ensure that the `caddy` labels match the service name. |
+| Kuma monitoring is not receiving updates | Missing `kuma.*` labels in service definition or incorrect logging levels | Ensure all required `kuma.*` labels are included in the service definition and adjust logging levels as needed. |
+
+---
+### Changelog
+
+| Date | Commit | Summary |
+|------|--------|---------|
+| 2026-05-01 | c9386fff | Initial documentation creation based on swarm/vscode.yaml. |
+| 2026-05-01 | c3b0c0f5 | Added environment variables and configuration details for secure setup. |
+| 2026-05-01 | 05fa151d | Improved user guide with example URL for accessing Code Server. |
+| 2026-01-20 | 10f15112 | Initial deployment of this Stack to NetGrimoire. |
+
+---
+### Notes
+- Generated by Gremlin on 2026-05-01T18:43:05.753Z
+- Source: swarm/vscode.yaml
+- Review User Guide and Changelog sections
\ No newline at end of file