# OpenVSCode Server

> VS Code in browser with Git and terminal.

- Category: Development Tools
- Difficulty: beginner
- Components: openvscode-server, nginx
- Tags: vscode, ide, browser, remote-dev
- Source: https://docker.recipes/development/openvscode-server-stack

## Overview

OpenVSCode Server is an open-source project developed by Gitpod that brings the full Microsoft Visual Studio Code experience to any web browser. Unlike traditional desktop IDEs, OpenVSCode Server runs as a web application, allowing developers to access their complete development environment from any device with internet connectivity. This browser-based approach eliminates the need for local VS Code installations while maintaining full compatibility with extensions, themes, and workspace configurations.

This stack combines OpenVSCode Server with NGINX to create a robust web-based development platform. NGINX serves as a high-performance reverse proxy, providing SSL termination, request routing, and static file serving capabilities that enhance the VS Code web interface. The combination addresses common challenges in remote development scenarios, including secure access management, performance optimization for large codebases, and reliable session handling for long-running development tasks.

Development teams working with distributed workflows, organizations requiring standardized development environments, and individual developers seeking device-independent coding solutions will find this stack particularly valuable. The OpenVSCode Server and NGINX pairing excels in scenarios where consistent development environments across team members are crucial, or when accessing powerful remote development servers from lightweight client devices like tablets or Chromebooks is necessary.

## Features

- Full Visual Studio Code interface accessible through any modern web browser
- Native support for VS Code extensions including language servers, debuggers, and themes
- Built-in terminal with shell access for command-line operations and Git workflows
- Token-based authentication system for secure remote access control
- Persistent workspace storage maintaining files, settings, and project state
- NGINX reverse proxy providing HTTP request optimization and static asset caching
- Multi-user workspace isolation through container user mapping
- Real-time file synchronization between browser interface and container filesystem

## Use cases

- Remote development teams needing consistent IDE environments across different operating systems
- Educational institutions providing standardized coding environments for students on various devices
- Developers working on resource-intensive projects requiring powerful server hardware
- Organizations implementing zero-trust security models with centralized development infrastructure
- Freelancers and consultants accessing client codebases from multiple locations and devices
- Code review workflows where reviewers need full IDE functionality without local setup
- Development on locked-down corporate networks where desktop software installation is restricted

## Prerequisites

- Docker Engine 20.10+ and Docker Compose V2 for container orchestration
- Minimum 2GB RAM allocation for OpenVSCode Server container operations
- Available ports 3000 and 80 for OpenVSCode Server and NGINX respectively
- Modern web browser with WebSocket support for real-time IDE functionality
- Basic understanding of VS Code extension management and workspace configuration
- File system permissions for volume mounting if using custom project directories

## docker-compose.yml

```yaml
services:
  openvscode-server:
    image: gitpod/openvscode-server:latest
    container_name: openvscode-server
    restart: unless-stopped
    ports:
      - "${VSCODE_PORT:-3000}:3000"
    environment:
      - CONNECTION_TOKEN=${CONNECTION_TOKEN}
    volumes:
      - vscode_home:/home/workspace
      - ${PROJECT_PATH:-./projects}:/home/workspace/projects
    user: "1000:1000"

  nginx:
    image: nginx:alpine
    container_name: vscode-nginx
    restart: unless-stopped
    ports:
      - "${NGINX_PORT:-80}:80"
    volumes:
      - ./nginx.conf:/etc/nginx/nginx.conf:ro

volumes:
  vscode_home:
```

## .env

```bash
# OpenVSCode Server
VSCODE_PORT=3000
CONNECTION_TOKEN=your_secure_token
PROJECT_PATH=./projects
NGINX_PORT=80
```

## Usage notes

- VS Code at http://localhost:3000
- Use token for authentication
- Mount project directories
- Install extensions as needed

## Troubleshooting

- Connection token authentication failing: Verify CONNECTION_TOKEN environment variable is set and matches the token used in browser URL
- Extensions not installing or loading: Check container has sufficient disk space and restart OpenVSCode Server container after failed installations
- File permissions denied in workspace: Ensure USER_ID and GROUP_ID environment variables match your host system user for proper volume mounting
- NGINX proxy errors or timeouts: Verify nginx.conf proxy_pass directive points to correct OpenVSCode Server container name and port
- Workspace files not persisting: Confirm vscode_home volume is properly created and mounted to /home/workspace in container
- Browser disconnections during large file operations: Increase NGINX proxy timeout values and WebSocket connection limits in configuration

