Skip to content

troubleshooting.md

Latest commit

 

History

History
55 lines (41 loc) · 3.13 KB

troubleshooting.md

File metadata and controls

55 lines (41 loc) · 3.13 KB

Troubleshooting

Common issues and their resolutions.

Connection Issues

404 Not Found / 403 Forbidden

  • DNS: Verify that your client machine can resolve the following subdomains:
    • desktop.<user>.remote-dev-box (for desktops)
    • traefik.remote-dev-box (for the dashboard)
    • Quick Fix: Ensure these are in your /etc/hosts or that your wildcard DNS is working.
  • Dashboard: The Traefik dashboard is accessible at https://traefik.${DOMAIN_NAME}/.
  • HTTPS: Ensure you are using https://, as KasmVNC and Traefik require TLS.
  • Auth: Double-check your credentials in users.htpasswd. Any valid user added via manage_users.sh can access the dashboard.
  • Docker API Version: If you see "client version 1.24 is too old" in Traefik logs, your Docker host requires a newer API version (minimum 1.44 for Docker 29+).
    • Fix: Upgrade Traefik to v3.6.1 or newer (e.g., v3.6.8).
    • Override: If using docker-compose.override.yml, ensure you override the traefik image version to a compliant release.

Bad Gateway (502)

  • This usually indicates the user container is starting or has crashed.
  • Check container status: ./admin/manage_users.sh list.
  • View logs: docker logs remote-dev-box-<username>.

Browser Warnings

"Your connection is not private"

  • This is expected when using self-signed certificates. Click Advanced -> Proceed to access the desktop.
  • For a more permanent fix, import the generated certs/full_cert.pem into your browser's trust store.

Graphical Issues

GUI Apps Crashing

  • Ensure the container was started with the correct Seccomp profile. This is handled automatically by the deployment scripts using admin/security/rdb.seccomp.json.
  • Check if your environment allows the userfaultfd or ptrace syscalls (if needed by your specific IDE flow), though these are restricted by default for security.

Admin Script Errors

Permission Denied

  • Ensure you have the necessary Docker permissions or use sudo.
  • Scripts in admin/ should be executable (chmod +x admin/*.sh).

RDB Routing & Smoke Testing

Test Fails (Exit Code 7 / Connection Refused)

  • Traefik Propagation: Traefik takes ~2-5 seconds to reload configuration when a new route is added. The test script waits 5 seconds by default, but slow remote hosts may need more.
  • Basic Auth: Ensure you haven't changed your password without updating the test environment (the test uses the username as the password by default for <username>).
  • RDB Daemon: Verify the proxy daemon is running: ps aux | grep rdb.

Test Fails (Exit Code 127 / Command Not Found)

  • Path: Ensure you are running the test from the root of the project or that rdb is in your PATH.
  • Provisioning: If ~/admin/testing/ is missing, ensure the box was created with the latest manage_users.sh.

Container stuck in "Restarting"

  • Seccomp: This is usually a Seccomp violation. Check dmesg on the host: sudo dmesg | grep seccomp.
  • If a required syscall is blocked, it must be added to admin/security/traefik.seccomp.json (for infrastructure) or admin/security/rdb.seccomp.json (for users).