mnemo_cards/tools/deploy/VSCODE_SERVER_SETUP.md

# VSCode Server Setup Guide

## Problem
After server reboot, VSCode Server (code-server) was not accessible:
- https://vscode.mnemo-cards.online/ - not working
- https://code.mnemo-cards.online/ - not working

## Root Causes Identified

1. **code-server was not configured to start on boot**
   - Service existed but wasn't properly enabled
   - Configuration file had wrong port (8080 instead of 8443)

2. **nginx configuration was missing**
   - VSCode nginx config wasn't deployed to the server
   - nginx was trying to use IPv6 (::1) instead of IPv4 (127.0.0.1)

3. **Domain conflict**
   - Both `code.mnemo-cards.online` and `vscode.mnemo-cards.online` were initially configured for VSCode
   - But `code.mnemo-cards.online` is actually used by Forgejo (git server)

## Solution

### Correct Domain Mapping
- **https://vscode.mnemo-cards.online/** → VSCode Server (code-server on port 8443)
- **https://code.mnemo-cards.online/** → Forgejo Git Server (port 3000)

### Fixed Components

#### 1. code-server Service
Created proper systemd service at `/etc/systemd/system/code-server.service`:
```ini
[Unit]
Description=code-server
After=network.target

[Service]
Type=simple
Environment=PASSWORD=AGktOidxrah1KVC0
ExecStart=/usr/bin/code-server --bind-addr 127.0.0.1:8443 --auth password
WorkingDirectory=/root
Restart=always
RestartSec=10
User=root

[Install]
WantedBy=multi-user.target
```

Configuration at `/root/.config/code-server/config.yaml`:
```yaml
bind-addr: 127.0.0.1:8443
auth: password
password: AGktOidxrah1KVC0
cert: false
```

#### 2. nginx Configuration
Deployed proper nginx configuration for vscode.mnemo-cards.online:
- Location: `/etc/nginx/sites-available/vscode.mnemo-cards.online`
- Proxy: http://127.0.0.1:8443 (using IPv4, not localhost which resolves to IPv6)
- SSL: Let's Encrypt certificates
- Rate limiting: Configured for login and general access
- WebSocket support: Enabled for VSCode

## Deployment Scripts

Created the following scripts in `tools/deploy/`:

1. **fix-vscode-server.sh** - Diagnoses and fixes code-server installation and configuration
2. **check-nginx.sh** - Checks nginx status and reloads configuration
3. **deploy-vscode-nginx.sh** - Deploys VSCode nginx configuration to server
4. **fix-nginx-duplicates.sh** - Removes duplicate nginx configurations
5. **test-vscode-from-server.sh** - Tests VSCode connectivity from server
6. **test-vscode-final.sh** - Final tests of both URLs

## How to Use

### Quick Fix After Server Reboot
If VSCode Server is not accessible after server reboot, run:
```bash
cd /Users/dmitry/StudioProjects/mnemo_cards/tools/deploy
./fix-vscode-server.sh
```

### Deploy nginx Configuration
To deploy or update nginx configuration:
```bash
cd /Users/dmitry/StudioProjects/mnemo_cards/tools/deploy
./deploy-vscode-nginx.sh
```

### Test Connectivity
To test if everything is working:
```bash
cd /Users/dmitry/StudioProjects/mnemo_cards/tools/deploy
./test-vscode-final.sh
```

## Access Information

- **URL**: https://vscode.mnemo-cards.online/
- **Username**: (no username required, password only)
- **Password**: AGktOidxrah1KVC0

## Service Management

### Check Status
```bash
ssh root@147.45.152.129
systemctl status code-server
```

### View Logs
```bash
ssh root@147.45.152.129
journalctl -u code-server -f
```

### Restart Service
```bash
ssh root@147.45.152.129
systemctl restart code-server
```

### Check nginx Status
```bash
ssh root@147.45.152.129
systemctl status nginx
nginx -t  # Test configuration
```

## Troubleshooting

### VSCode Server Not Starting
1. Check if service is running: `systemctl status code-server`
2. Check logs: `journalctl -u code-server -n 50`
3. Verify port is listening: `ss -tuln | grep 8443`
4. Run fix script: `./fix-vscode-server.sh`

### nginx 502 Bad Gateway
1. Verify code-server is running on port 8443
2. Check nginx error logs: `tail -f /var/log/nginx/error.log`
3. Verify proxy_pass uses 127.0.0.1:8443 (not localhost)

### SSL Certificate Issues
Certificates are managed by Let's Encrypt and stored at:
```
/etc/letsencrypt/live/vscode.mnemo-cards.online/
```

To renew certificates:
```bash
ssh root@147.45.152.129
certbot renew
systemctl reload nginx
```

## Architecture

```
Internet
    ↓
nginx (port 443) - SSL termination
    ↓
code-server (127.0.0.1:8443) - VSCode Server
    ↓
/root/ - Working directory
```

## Notes

- code-server runs as root user (WorkingDirectory=/root)
- Authentication is enabled with password
- WebSocket support is enabled for VSCode features
- Rate limiting is configured to prevent abuse
- Automatic restart is configured (Restart=always)
- Service is enabled to start on boot (enabled via systemctl)

## Recent Changes (2025-11-19)

1. ✅ Fixed code-server service configuration
2. ✅ Deployed nginx configuration
3. ✅ Fixed IPv6/IPv4 issue (localhost → 127.0.0.1)
4. ✅ Resolved domain conflict (removed code.mnemo-cards.online from VSCode config)
5. ✅ Enabled service auto-start on boot
6. ✅ Verified both URLs are working

## Status

🟢 **OPERATIONAL**
- vscode.mnemo-cards.online - Working ✅
- code.mnemo-cards.online - Working ✅ (Forgejo)