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:

[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:

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. fix-vscode-rate-limit.sh - Fixes 429 errors by updating rate limits in nginx.conf
3. check-nginx.sh - Checks nginx status and reloads configuration
4. deploy-vscode-nginx.sh - Deploys VSCode nginx configuration to server
5. fix-nginx-duplicates.sh - Removes duplicate nginx configurations
6. test-vscode-from-server.sh - Tests VSCode connectivity from server
7. 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:

cd /Users/dmitry/StudioProjects/mnemo_cards/tools/deploy
./fix-vscode-server.sh

Deploy nginx Configuration

To deploy or update nginx configuration:

cd /Users/dmitry/StudioProjects/mnemo_cards/tools/deploy
./deploy-vscode-nginx.sh

Test Connectivity

To test if everything is working:

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

ssh root@147.45.152.129
systemctl status code-server

View Logs

ssh root@147.45.152.129
journalctl -u code-server -f

Restart Service

ssh root@147.45.152.129
systemctl restart code-server

Check nginx Status

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)

429 Too Many Requests

If you get 429 (Too Many Requests) errors when loading VSCode:

1. Run the fix script: ./fix-vscode-rate-limit.sh
2. Redeploy nginx config: ./deploy-vscode-nginx.sh
3. The issue is usually caused by too strict rate limiting for static files
4. Static files are now excluded from rate limiting automatically

SSL Certificate Issues

Certificates are managed by Let's Encrypt and stored at:

/etc/letsencrypt/live/vscode.mnemo-cards.online/

To renew certificates:

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:
  • General requests: 200 requests/minute (burst: 50)
  • Login attempts: 5 requests/minute (burst: 2)
  • Static files (JS, CSS, images): No rate limiting
• Automatic restart is configured (Restart=always)
• Service is enabled to start on boot (enabled via systemctl)

Recent Changes

2025-11-22

1. ✅ Fixed 429 (Too Many Requests) error for static files
   • Excluded static files (/static/, /out/, file extensions) from rate limiting
   • Increased general rate limit from 30r/m to 200r/m
   • Added caching for static files

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)