CONTRIBUTING.md

❤️‍🔥 Contributing to this project

Thank you for your interest in contributing to freerdp-novnc.

🐛 Reporting issues

Please report issues in our GitHub repository. Before submitting an issue, please search for existing issues to avoid duplicates.

🏗️ Project overview

This project provides a Docker image serving FreeRDP over noVNC on a virtual X display, accessible from a web browser.

🛠️ Tech stack

This project uses the following tech stack:

• Debian 13 (trixie) as base image
• freerdp3-x11 for RDP client
• x11vnc, websockify, Xvfb and noVNC for browser-based VNC access
• Fluxbox for window management
• Supervisor for process management
• shfmt and shellcheck for formatting and linting shell scripts, and BATS for running tests

📂 Key directory structure

• docs/: Documentation resources
• supervisord/: Supervisor configuration files
• test/: Project tests
• docker-compose.yaml: Docker Compose configuration for local development and testing
• docker-entrypoint.sh: Docker entrypoint script
• Dockerfile: Docker image definition
• flake.nix: Nix Flakes development environment
• Justfile: Commands for development

🔧 Set up the development environment

For development, the following tools are required:

🐳 System requirements

You need Docker and Docker Compose installed on your system.

❄️ Tools managed via Nix Flakes

This repository uses Nix Flakes to manage development tools. The following tools are installed automatically when nix is available:

• pre-commit
• just
• shfmt
• shellcheck
• freerdp

Simply run nix develop to enter the development environment, then run just install to set up dependencies. The Nix shell also installs the pre-commit hooks automatically.

If you prefer using a Dev Container, an example configuration file (devcontainer.json) is provided with Nix and Docker-in-Docker pre-installed.

✅ Verifying changes

Before pushing your code, run just ci to verify that your changes adhere to the project's coding standards and pass all linters, formatters, and tests.

Alternatively, use the pre-commit hooks to handle formatting, linting, and quick test feedback automatically.

✨ Submitting changes

Please feel free to submit pull requests on GitHub. Before opening a PR, ensure your changes pass all checks by running just ci.

🚀 Release process

The Docker image is published to Docker Hub automatically on pushes to the main branch. To release a new version, create a release in GitHub Releases with a v* tag, which will trigger the publish.yaml workflow to build and push the Docker image with semantic version tags.