portainer-core/docs/guides/code-server-setup.md

# Code-Server Installation Guide

> Browser-based VSCode IDE running on host for full system access
>
> **Service Type:** Host-based (systemd service, not containerized)
> **Purpose:** Replace SSH with persistent web-based development environment
> **Access:** https://code.schweitz.net (via NPM with SSL)

---

## Why Host-Based?

Unlike other services in this stack, code-server runs directly on the host OS (not in Docker) to provide:

- Full access to host filesystem and configurations
- Direct control over systemd services
- Native Docker CLI access without Docker-in-Docker complexity
- No permission issues when editing files across SSD/HDD
- Persistent sessions that survive network disconnections

---

## Installation Steps

### 1. Install code-server

Run these commands on the tower-of-joy host:

```bash
# Download and install code-server (version 4.x)
curl -fsSL https://code-server.dev/install.sh | sh

# Verify installation
code-server --version
```

### 2. Create Configuration Directory

```bash
# Create config directory
mkdir -p ~/.config/code-server

# Create configuration file
cat > ~/.config/code-server/config.yaml <<'EOF'
bind-addr: 127.0.0.1:8084
auth: password
password: CHANGE_THIS_PASSWORD
cert: false
user-data-dir: /home/jpmschweitzer/docker-data/code-server/user-data
extensions-dir: /home/jpmschweitzer/docker-data/code-server/extensions
EOF

# Create data directories on SSD
mkdir -p /home/jpmschweitzer/docker-data/code-server/{user-data,extensions}
```

**IMPORTANT:** Replace `CHANGE_THIS_PASSWORD` with a strong password. This is a secondary auth layer (NPM will provide the primary authentication).

### 3. Create Systemd Service

```bash
# Create service file
sudo tee /etc/systemd/system/code-server.service > /dev/null <<'EOF'
[Unit]
Description=code-server - Browser-based VSCode IDE
Documentation=https://coder.com/docs/code-server
After=network.target

[Service]
Type=exec
ExecStart=/usr/bin/code-server
Restart=always
User=jpmschweitzer
Group=jpmschweitzer
Environment="PASSWORD_FROM_CONFIG=true"

# Hardening
NoNewPrivileges=true
PrivateTmp=true
ProtectSystem=full
ProtectHome=false
ReadWritePaths=/home/jpmschweitzer /mnt/media

[Install]
WantedBy=multi-user.target
EOF

# Reload systemd daemon
sudo systemctl daemon-reload

# Enable and start code-server
sudo systemctl enable code-server
sudo systemctl start code-server

# Check status
sudo systemctl status code-server
```

### 4. Verify Local Access

```bash
# Test that code-server is running locally
curl -I http://127.0.0.1:8084

# Should return HTTP 302 (redirect to login page)
```

---

## Service Integration

### Uptime Kuma Monitoring

After code-server is running, add it to Uptime Kuma for health monitoring:

1. Open Uptime Kuma: http://192.168.86.149:3001
2. Click **Add New Monitor**
3. Configure the monitor:

**Monitor Settings:**
- **Monitor Type:** HTTP(s)
- **Friendly Name:** Code-Server
- **URL:** https://code.schweitz.net
- **Heartbeat Interval:** 60 seconds
- **Retries:** 3
- **Heartbeat Retry Interval:** 60 seconds
- **Accepted Status Codes:** 200-299, 302 (redirect to login)
- **Ignore TLS/SSL errors:** ❌ Disabled (cert should be valid)
- **Tags:** Infrastructure, Development

4. Click **Save**

The monitor should show "Up" status once code-server is accessible through NPM.

### Organizr Dashboard Integration

Add code-server to your Organizr unified dashboard:

1. Open Organizr: https://home.schweitz.net
2. Navigate to **Settings → Tab Editor**
3. Click **Add Tab**

**Tab Configuration:**
- **Tab Name:** Code-Server
- **Tab URL:** https://code.schweitz.net
- **Category:** Infrastructure (or create "Development" category)
- **Icon:** `fa-code` or `fa-laptop-code`
- **Active:** ✅ Enabled
- **New Window:** ❌ Disabled (use iframe)

4. **Homepage Integration (Optional):**
   - Go to **Settings → Homepage Items**
   - Add custom HTML tile:

```html
<div class="homepage-item">
  <a href="https://code.schweitz.net" target="_blank">
    <i class="fa fa-code fa-3x"></i>
    <span>Code-Server</span>
  </a>
</div>
```

5. Click **Save**

The code-server tab will now appear in your Organizr sidebar.

---

## Nginx Proxy Manager Configuration

### Create Proxy Host

1. Open NPM admin interface: http://192.168.86.149:81
2. Navigate to **Hosts → Proxy Hosts → Add Proxy Host**

**Details Tab:**
- **Domain Name:** `code.schweitz.net`
- **Scheme:** `http`
- **Forward Hostname/IP:** `192.168.86.149` (or `localhost`)
- **Forward Port:** `8084`
- **Block Common Exploits:** ✅ Enabled
- **Websockets Support:** ✅ Enabled (critical for code-server)

**SSL Tab:**
- **SSL Certificate:** Request New SSL Certificate
- **Force SSL:** ✅ Enabled
- **HTTP/2 Support:** ✅ Enabled
- **HSTS Enabled:** ✅ Enabled
- **Email:** your-email@example.com (for Let's Encrypt)
- **Terms of Service:** ✅ Agree

**Access List Tab:**
- Create new access list: "Code Server Access"
- Configure basic auth or use NPM's built-in authentication

**Advanced Tab (optional):**
```nginx
# Increase timeout for long-running operations
proxy_read_timeout 3600s;
proxy_send_timeout 3600s;

# Proper headers for WebSocket support
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "upgrade";
proxy_set_header Accept-Encoding gzip;
```

---

## Security Hardening

### Firewall Rules

```bash
# Ensure port 8084 is NOT exposed to the internet
sudo ufw status

# Port 8084 should only be accessible from localhost
# External access ONLY through NPM on ports 80/443
```

### Authentication Layers

Code-server will have **three layers of security**:

1. **NPM Access List** - Primary authentication via reverse proxy
2. **code-server password** - Secondary authentication (from config.yaml)
3. **HTTPS/SSL** - Encrypted transport via Let's Encrypt

### Recommended NPM Access List

Create an access list in NPM with:
- Basic Auth username/password
- IP whitelist (optional): Restrict to known IPs or Tailscale network
- Rate limiting: Prevent brute force attacks

---

## Configuration Tips

### Extensions to Install

After first login, install these extensions:

```bash
# Via code-server CLI
code-server --install-extension ms-python.python
code-server --install-extension ms-azuretools.vscode-docker
code-server --install-extension eamodio.gitlens
code-server --install-extension GitHub.copilot  # If you have Copilot
code-server --install-extension Codeium.codeium  # Free AI assistant alternative
```

### Custom Settings

Edit settings via UI or directly:

```bash
nano ~/docker-data/code-server/user-data/User/settings.json
```

Recommended settings:
```json
{
  "workbench.colorTheme": "Default Dark+",
  "terminal.integrated.defaultProfile.linux": "bash",
  "files.watcherExclude": {
    "**/node_modules/**": true,
    "**/.git/objects/**": true,
    "**/.venv/**": true
  },
  "editor.formatOnSave": true,
  "files.autoSave": "afterDelay"
}
```

---

## Maintenance

### View Logs

```bash
# Systemd logs
sudo journalctl -u code-server -f

# Follow recent logs
sudo journalctl -u code-server --since "10 minutes ago"
```

### Restart Service

```bash
sudo systemctl restart code-server
```

### Update code-server

```bash
# Re-run installation script
curl -fsSL https://code-server.dev/install.sh | sh

# Restart service to use new version
sudo systemctl restart code-server
```

### Backup Configuration

Configuration is stored in:
- `~/.config/code-server/config.yaml` - Main config
- `~/docker-data/code-server/user-data/` - Settings, keybindings, snippets
- `~/docker-data/code-server/extensions/` - Installed extensions

**Automated Backups:**

The maintenance container backs up code-server configuration nightly at 3 AM to `/mnt/media/backups/docker-configs/` with 30-day retention.

After installing code-server, restart the maintenance container to enable backups:

```bash
docker restart maintenance

# Verify the mount is accessible
docker exec maintenance ls -la /data/code-server-config

# Manually trigger a backup to test
docker exec maintenance /scripts/backup-configs.sh

# Check backup logs
docker exec maintenance cat /var/log/maintenance/backup-configs.log
```

---

## Troubleshooting

### Service won't start

```bash
# Check service status
sudo systemctl status code-server

# Check logs for errors
sudo journalctl -u code-server -n 50

# Verify config file syntax
cat ~/.config/code-server/config.yaml
```

### Can't connect via browser

```bash
# Verify code-server is listening
sudo netstat -tlnp | grep 8084

# Check NPM proxy host configuration
# Ensure WebSocket support is enabled
# Verify SSL certificate is valid
```

### Performance issues

```bash
# Check system resources
htop

# Monitor code-server process
top -p $(pgrep code-server)

# Increase file watcher limits if needed
echo fs.inotify.max_user_watches=524288 | sudo tee -a /etc/sysctl.conf
sudo sysctl -p
```

---

## Integration Checklist

- [ ] code-server installed and running via systemd
- [ ] NPM proxy host configured with SSL
- [ ] External access working at https://code.schweitz.net
- [ ] WebSocket connections working (terminal, file watcher)
- [ ] Authentication layers tested (NPM + code-server password)
- [ ] Maintenance container restarted to enable backups
- [ ] Backup tested and verified
- [ ] Uptime Kuma monitoring added
- [ ] Organizr dashboard tab created
- [ ] CONTAINERS.md documentation updated
- [ ] README.md service table updated

---

## References

- **Code-Server Docs:** https://coder.com/docs/code-server
- **NPM Docs:** https://nginxproxymanager.com/guide/
- **Systemd Docs:** https://www.freedesktop.org/software/systemd/man/systemd.service.html

---

*Created: 2025-11-14*
*System: tower-of-joy*