Cómo autoalojar code-server en 2026: WebSockets, workspaces y control de acceso

Un despliegue fallido de code-server no siempre se cae. Puede mostrar una página de inicio de sesión mientras el proxy bloquea los WebSockets o los permisos de los archivos impiden instalar extensiones. En su lugar, empieza con una comprobación de extremo a extremo: inicia sesión, abre un repositorio montado, crea un archivo, ejecuta un comando en el terminal, instala una extensión y vuelve a conectar el WebSocket del editor.

Esta comprobación coincide con el propósito catalogado de code-server: ejecutar VS Code en el navegador sobre una máquina remota. También permite detectar antes las dependencias que faltan, las suposiciones incorrectas sobre el proxy y los datos efímeros que una comprobación de disponibilidad no detectaría.

De qué depende code-server

Traza tres límites alrededor de code-server: la entrada al puerto 8080, el estado persistente y los requisitos de soporte. El contenedor se puede reemplazar, pero los otros dos necesitan responsables explícitos. El requisito del runtime local es un mount de workspace que contenga únicamente los proyectos a los que el editor debe acceder. Comprueba ese límite antes de publicar el servicio y de nuevo después de reemplazar un contenedor.

El diagrama está completo cuando un cliente limpio puede iniciar sesión, abrir un repositorio montado, crear un archivo, ejecutar un comando en el terminal, instalar una extensión y volver a conectar el WebSocket del editor. Recoge datos de tiempos y recursos sobre la memoria y la CPU utilizadas por los language servers, las compilaciones, los extension hosts y los terminales, no por la shell web de code-server. Si la transacción falla, el primer límite que no se comporta según lo documentado indica si debes investigar el routing, la capacidad local o un servicio de soporte.

Convierte el comando local en un servicio inspeccionable

Un lanzamiento con forma de producción es deliberadamente aburrido: estado con nombre, puerto explícito y ningún secreto dentro de la imagen.

docker run -d \
  --name code-server \
  --restart unless-stopped \
  -p 127.0.0.1:8080:8080 \
  -v code-server-data:/home/coder \
  -e PASSWORD=replace-with-a-long-random-value \
  codercom/code-server:latest \
  --bind-addr 0.0.0.0:8080 --auth password .

El ejemplo es una base, no un stack de soporte completo. Confirma el requisito local antes de exponer el servicio: un mount de workspace que contenga únicamente los proyectos a los que el editor debe acceder. Comprueba los mounts efectivos y el listener, y después intenta iniciar sesión, abrir un repositorio montado, crear un archivo, ejecutar un comando en el terminal, instalar una extensión y volver a conectar el WebSocket del editor. Fija la imagen que funciona antes del siguiente reinicio.

Haz que el origen público no sea ambiguo

Coloca el editor detrás de HTTPS y conserva las actualizaciones de WebSocket. Envía el hostname elegido al puerto 8080 del contenedor, reenvía el host original y el esquema HTTPS, y evita publicar un segundo origen directo.

Prueba code-server desde un cliente externo limpio. Separa el fallo de entrada del límite conocido de la aplicación: el proxy bloquea los WebSockets o los permisos de los archivos impiden instalar extensiones. Un error de certificado, DNS o 502 pertenece al routing; una solicitud que llega a code-server y falla después pertenece al estado de la aplicación, a la capacidad o a uno de sus requisitos de soporte. La guía de TLS para dominios personalizados cubre el primer grupo.

Haz copias de seguridad del estado que code-server no puede recrear

Una imagen de contenedor se puede descargar de nuevo; la configuración, las extensiones y los directorios de proyectos montados explícitamente no. Monta /home/coder antes del bootstrap, escribe datos de ejemplo inocuos y reemplaza el contenedor para demostrar que esa ruta es realmente persistente. Inspecciona el mount efectivo en lugar de confiar en el nombre de un archivo de Compose y comprueba que el usuario del runtime puede escribir donde code-server lo necesita.

Elige la retención y un destino externo al host, y después ensaya la recuperación sin tocar producción. El simulacro solo se supera cuando la configuración, las extensiones y los archivos del workspace vuelven con los permisos correctos y el terminal se inicia con el usuario previsto. Para el estado respaldado por una base de datos, combina snapshots del almacenamiento con exports coherentes con la aplicación, tal como se describe en recuperación point-in-time frente a snapshots.

Refuerza la seguridad de code-server después del bootstrap

En code-server, la superficie valiosa no es necesariamente la landing page. El error principal es conceder al contenedor acceso al socket de Docker o a todo el filesystem del host de forma poco cuidadosa. Contrarréstalo de forma deliberada: monta únicamente los workspaces previstos, evita el socket de Docker del host y coloca el editor detrás de HTTPS y de una autenticación sólida.

Sustituye inmediatamente el PASSWORD de ejemplo, guárdalo fuera de la imagen y rótalo como una credencial de administrador si queda expuesto. Usa un usuario de contenedor sin privilegios cuando la imagen lo admita y no montes credenciales que no estén relacionadas. Aplica límites de rate o de tamaño en la entrada cuando el trabajo no confiable pueda consumir memoria y CPU utilizadas por los language servers, las compilaciones, los extension hosts y los terminales, en lugar de por la shell web de code-server.

Diagnostica un code-server que parece saludable

Observa el trabajo que realiza code-server: la memoria y la CPU utilizadas por los language servers, las compilaciones, los extension hosts y los terminales, no por la shell web de code-server. Define límites dejando margen para ese trabajo y evita una liveness probe que compita con él. La comprobación del operador debe seguir intentando iniciar sesión, abrir un repositorio montado, crear un archivo, ejecutar un comando en el terminal, instalar una extensión y volver a conectar el WebSocket del editor de forma programada.

Para las actualizaciones, recuerda que la compatibilidad de las extensiones y las toolchains de la imagen base pueden cambiar aunque la UI de code-server siga iniciándose. Despliega el candidato sobre una copia recuperada y repite la prueba conocida. Si el proxy bloquea los WebSockets o los permisos de los archivos impiden instalar extensiones, utiliza los logs del runtime y la solicitud de red real para descubrir qué supuesto ha cambiado.

Evidencias que debes recopilar antes de poner code-server en producción

Crea un fixture de code-server pequeño y desechable, y consérvalo para cada release. El fixture debe probar el workflow real: iniciar sesión, abrir un repositorio montado, crear un archivo, ejecutar un comando en el terminal, instalar una extensión y volver a conectar el WebSocket del editor. Registra el digest de la imagen, el hostname externo, la dirección de la dependencia y el resultado esperado para que otro operador pueda repetir la prueba más adelante sin tener que interpretar esta guía.

Ejecuta el fixture tres veces. Primero, utiliza el despliegue nuevo. Segundo, reemplaza el contenedor sin tocar el estado persistente. Tercero, restaura la copia de seguridad en un entorno vacío. La tercera ejecución solo se supera cuando la configuración, las extensiones y los archivos del workspace vuelven con los permisos correctos y el terminal se inicia con el usuario previsto. Durante cada ejecución, captura la latencia y el uso de recursos alrededor de la memoria y la CPU utilizadas por los language servers, las compilaciones, los extension hosts y los terminales, no por la shell web de code-server; esto se convierte en la línea base de las alertas, en lugar de un porcentaje de CPU arbitrario.

Por último, prueba deliberadamente la ruta negativa: envía una entrada inocua cerca del límite de recursos o de formato asociado a este límite: el proxy bloquea los WebSockets o los permisos de los archivos impiden instalar extensiones. Confirma que code-server falla de forma visible sin corromper el estado, restablece la condición correcta y repite la transacción satisfactoria. Un registro del release que contenga esos cuatro resultados proporciona evidencias más sólidas que las capturas de un dashboard o una respuesta puntual de curl.

Traslada el trabajo de infraestructura repetible a Dockup

Dockup puede encargarse de las piezas reemplazables de la plataforma: dirigir el tráfico al puerto 8080, emitir el dominio y el certificado, inyectar secretos, conectar el almacenamiento persistente y conectar code-server con servicios gestionados o conectados de forma privada. Puede hacerlo en la infraestructura de Dockup o en un servidor que conectes.

El trabajo de aceptación de code-server sigue siendo explícito. Después del despliegue con un clic, coloca el editor detrás de HTTPS y conserva las actualizaciones de WebSocket, confirma el requisito local —un mount de workspace que contenga únicamente los proyectos a los que el editor debe acceder— y ejecuta este escenario: inicia sesión, abre un repositorio montado, crea un archivo, ejecuta un comando en el terminal, instala una extensión y vuelve a conectar el WebSocket del editor. Esta división es intencionada: Dockup elimina la configuración repetitiva de infraestructura sin fingir que los roles de la aplicación, las credenciales del proveedor o la política de restauración se eligen por sí solos.

Preguntas frecuentes

¿Qué necesita code-server para un despliegue de producción?

Dirige el contenedor de code-server en el puerto 8080 a través de un único origen HTTPS. El requisito del runtime local es un mount de workspace que contenga únicamente los proyectos a los que el editor debe acceder. No des por listo code-server hasta que puedas iniciar sesión, abrir un repositorio montado, crear un archivo, ejecutar un comando en el terminal, instalar una extensión y volver a conectar el WebSocket del editor.

¿Qué datos de code-server deben incluirse en una copia de seguridad?

Haz persistir /home/coder e incluye la configuración, las extensiones y los directorios de proyectos montados explícitamente en el mismo manifiesto de recuperación. Una restauración limpia de code-server solo se supera cuando la configuración, las extensiones y los archivos del workspace vuelven con los permisos correctos y el terminal se inicia con el usuario previsto.

¿Necesita code-server HTTPS detrás de un reverse proxy?

Usa HTTPS para el origen público de code-server y mantén el puerto 8080 en la ruta interna. Aplica correctamente la configuración de code-server: coloca el editor detrás de HTTPS y conserva las actualizaciones de WebSocket. En code-server, HTTPS protege las credenciales o el contenido del usuario durante el tránsito y mantiene coherente el comportamiento del cliente sensible al origen.

¿Cómo debe probarse una actualización de code-server?

Restaura el estado actual de code-server en un despliegue aislado, aplica la versión candidata y repite su transacción de aceptación. Presta especial atención, porque la compatibilidad de las extensiones y las toolchains de la imagen base pueden cambiar aunque la UI de code-server siga iniciándose. Conserva la imagen anterior de code-server hasta comprender los límites de migración de datos y rollback.