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

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)

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
• 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)