{"id":13587823,"url":"https://github.com/andif888/workfromhome-with-docker","last_synced_at":"2025-04-29T22:31:19.034Z","repository":{"id":95852728,"uuid":"247326214","full_name":"andif888/workfromhome-with-docker","owner":"andif888","description":"HTML5 based remote desktop gateway using Apache Guacamole and Traefik Reverse Proxy including AD authentication and 2-FA","archived":false,"fork":false,"pushed_at":"2022-01-28T18:21:46.000Z","size":548,"stargazers_count":74,"open_issues_count":0,"forks_count":20,"subscribers_count":8,"default_branch":"master","last_synced_at":"2024-02-13T21:57:43.804Z","etag":null,"topics":["activedirectory","docker","guacamole","homelab","html5","letsencrypt","multifactor-authentication","rdp","remote-desktop","remotedesktopgateway","traefik","work-from-home"],"latest_commit_sha":null,"homepage":"","language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/andif888.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null}},"created_at":"2020-03-14T17:54:05.000Z","updated_at":"2024-02-13T21:57:44.129Z","dependencies_parsed_at":"2023-03-13T16:44:43.083Z","dependency_job_id":null,"html_url":"https://github.com/andif888/workfromhome-with-docker","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/andif888%2Fworkfromhome-with-docker","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/andif888%2Fworkfromhome-with-docker/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/andif888%2Fworkfromhome-with-docker/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/andif888%2Fworkfromhome-with-docker/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/andif888","download_url":"https://codeload.github.com/andif888/workfromhome-with-docker/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":251593043,"owners_count":21614465,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["activedirectory","docker","guacamole","homelab","html5","letsencrypt","multifactor-authentication","rdp","remote-desktop","remotedesktopgateway","traefik","work-from-home"],"created_at":"2024-08-01T15:06:22.689Z","updated_at":"2025-04-29T22:31:18.285Z","avatar_url":"https://github.com/andif888.png","language":"Shell","funding_links":[],"categories":["Shell"],"sub_categories":[],"readme":"\n# WorkFromHome-with-Docker\n\n*\"Navigate in any webbrowser to https://desktops.yourcompany.com and logon with your corporate Active Directory account (including 2-FA) to access your Windows desktops\"*  \n\nIf you want your users to be able to access for example Windows PCs or Windows RDS, which are located on your corporate network from anywhere in the world using any HTML5 capable webbrowser, then this is right for.   \nIf your are a homelab enthusiast and want your homelab to be accessible from any where from any device using HTML5, then this maybe worth to have a look.\n\n![WorkFromHome-with-Docker](images/workfromhome-with-docker-920.png)\n\nThis repo runs a bunch of docker containers on any Linux operating system to make this possible. \n\n[Traefik](https://github.com/containous/traefik/) is used as a reverse proxy, which responsible for automatically requesting and renewing a Letsencrypt certificate for SSL terminiation and securing the network traffic. HTTPS request are proxied into Apache Guacamole.\n\n[Apache Guacamole](https://guacamole.apache.org) is a clientless remote desktop gateway, which supports protocols like RDP, VNC and SSH. Because the Guacamole client is an HTML5 web application, use of your computers is not tied to any one device or location. As long as you have access to a web browser, you have access to your machines.\n\nThis repo automates the whole configuration and integration of Traefik and Apache Guacamole. By setting a few mandatory environment variables, user authentication can be integrated into Active Directory using LDAP. Also 2-FA-Authentication is enabled using Google-Authenticator or any compatible TOTP implementation.   \n\nIf you are not afraid of Linux, Docker and a bunch of Opensource Tools, then you are there **in a few minutes**.\n\n\n## How to use this repo\n\n### Pre-requesites\n\nIdeally you have a vanilla or an existing Ubuntu server on your corporate network. \nYour internet router should forward all network traffic, incomming from the internet on port `80` and `443` to the internal IP address and port 80 and 443 of your Ubuntu server. Port 80 is used by Letsencrypt for httpChallenge for automatic SSL certificate request an renewals. Port 443 is actually used by the secured HTTPS traffic.\nYou should register a public DNS hostname - for example `desktops.yourcompany.com` - which points to the external IP address your internet router. \nIf your external IP address of your internet router is not a static one, but changes sometimes, then dynamic DNS updates is your friend, which is often an already built-in feature of your internet router and works usually very reliable.  \nNOTE: You can easily set your DynDNS-Name as CNAME to `desktops.yourcompany.com` in your public DNS.  \n\n**Pro-Tip**: Maybe you have spotted the [Vagrantfile](Vagrantfile). This means, for testing purpose you can use `vagrant up` to spin up an Ubuntu Linux immediately, if you are a little bit familiar with [Vagrant](https://www.vagrantup.com/downloads.html) and [VirtualBox](https://www.virtualbox.org/wiki/Downloads) and have already installed it somewhere. If you do so then you can already skip `Step 1`, because Vagrant has done it already for you. \n\n\n### Step 1:\n\nRun the [install.sh](install.sh) script as root on your Ubuntu server. \nThis script automatically installs docker, docker-compose and git. It also clones this repo into the directoy `/srv/workfromhome-with-docker` on your server.\n\n```console\nsudo -s\ncurl -sfL https://raw.githubusercontent.com/andif888/workfromhome-with-docker/master/install.sh | sh -\n```\n\n### Step 2:\n\nEdit the [.env](.env) file and customize at least the values of the mandatory environment variables with your preferred text editor. All mandatory an optional setting are documented inside the .env file.\n\n```console\ncd /srv/workfromhome-with-docker\nnano .env \n```\n\n### Step 3:\n\nStart docker container using the [start.sh](start.sh) script.\n\n```console\n./start.sh\n```\n\n### Step 4:\n\nPoint your preferred webbrowser to the DNS host name, which you have configured as `FQDN_HOST_NAME` in your .env file. \nExample: [https://desktops.yourdomain.com](https://desktops.yourdomain.com)  \nThe default username is `guacadmin` and password is `guacadmin`. \n\n(If you currently can not access your external `FQDN_HOST_NAME` from internally, you can verify it from internally using http://ubuntu-internal-ip:8081/guacamole   \nAlternatively add a hosts file entry, which points your `FQDN_HOST_NAME` to the internal IP of your Ubuntu Server -\u003e [Beginner-Guide-to-edit-your-hosts-file](https://www.howtogeek.com/howto/27350/beginner-geek-how-to-edit-your-hosts-file/)) \n\nAfter entering credentials your prompted to scan the QR-Code, with a compatible TOTP App on your mobile phone.   \n[**Google Authenticator**](https://play.google.com/store/apps/details?id=com.google.android.apps.authenticator2\u0026hl=en) works good.\n\n![Guacamole 2FA QR-Code](images/00-guac-2fa-qr.png)\n\nAfter scanning the QR-Code and entering the first token your are successfully logged into Apache Guacamole.  \n**Please change the default password immediatelly**.\n\n\n## Configure your first Windows Machine accessible through Guacamole, which has RDP enabled\n\nClick `Settings` in the top right menu. \n\n![Guacamole Settings Menu](images/01-guac-settings.png)\n\n\nClick `Connections` and the `New Connection` \n\n![Guacamole Connection Menu](images/02-guac-connection-new.png)\n\n\nEnter any Name. It's only a display name. \nSelect `RDP` as Protocol. \n\n![Guacamole Edit Connection](images/03-guac-connection-edit01.png)\n\n\nScroll down to `Parameters` and enter the RDP connection details.\n\n![Guacamole Edit Connection 02](images/04-guac-connection-edit02.png)\n\n\nOptionally fine-tune for latest RDP-Protocol version. \nAnd finally hit `Save` at the bottom of the page.\n\n![Guacamole Edit Connection 03](images/05-guac-connection-edit03.png)\n\n\nGo back to `Home` \n\n![Guacamole home](images/06-guac-home.png)\n\nAnd start the connection\n\n![Guacamole home start connection](images/07-guac-home-start-connection.png)\n\nand have fun! HTML5 based RDP into your Windows machine.\n\n![Guacamole home start connection](images/08-guac-home-started.png) \n\n\nGeneral Help on [How to configure connections in Guacamole](https://guacamole.apache.org/doc/gug/configuring-guacamole.html#connection-configuration)\n\n\n## Using Active Directory Authentication and enable 2-FA \n\nMake sure you have entered correct mandatory values regarding LDAP authentication into the [.env](.env) file in **Step 2** during initial configuration.   \nNOTE: We don't use the AD Schema preparation, documented at https://guacamole.apache.org/doc/gug/ldap-auth.html, because we don't like to do changes in our Active Directory Schema. \nPlease read the documention to understand the mapping between database users und AD users.\n\n### Step 1: Create an initial admin user in Guacamole which maps to an AD user \n\nCreate a new user in Guacamole and set its username to the username of an existing AD user, which is located in your AD-Tree below the OU (Organizational Unit), which you have configured in `LDAP_USER_BASE_DN` environment variable.\n\nIf you haven't changed `LDAP_USERNAME_ATTRIBUTE` then the mapped username of your AD user is the `userPrincipalName` AD-Attribute.\nYour can set any password. It **must not** match your AD user's password.\nMake sure you check all permissions and hit `Save` at the bottom of the page.\n\n![Guacamole home start connection](images/09-guac-ad-user.png) \n\n\n### Step 2: Logon with your newly mapped AD user account\n\nNow you should be able to logon with the AD user account.   \nBecause of we have previously set the permission `Change own password`, we are prompted with the already familiar 2-FA screen. Again use your Google Authenticator to scan the QR-Code. \n\nIf you now navigate to `Settings -\u003e Users` you should get already a list of  your AD user accounts, which means, your LDAP integration and authentication is working perfect.\n\n### Step 3: Enable 2-FA for and AD user\n \n If you want to enable 2-FA for AD user then you minimum need to assign the permission `Change own password` on his user account.  \n Don't be afraid of the setting, it doesn't mean a user can change its AD password using this web GUI. It's only about changing its personal credential information in Guacamole's MySQL database, which is necessary to write down the TOTP secret key.\n\n\n## The best thing at the Bottom: Pass-Through credentials to a connection \n\nYou have already learned to create your first connection to a Windows machine further above.  \nThere is a nice feature which allows you to pass-through your Guacamole logon credentials to a connection.   \n\nYou remember when you have scrolled down to `Parameters` and entered the RDP connection details?  \nTo enable Pass-Through credentials you do not hardcode username and password. You only need to enter **parameter tokens**. \n\nFor the username you enter `${GUAC_USERNAME}`   \nFor the password you enter `${GUAC_PASSWORD}` \n\nIf you use the `userPrincipalName` for your AD users all is perfect and no need to worry about the Domain field ;-)\n\n![Guacamole Pass-Through Credentials](images/10-guac-pass-through-creds.png) \n\nTo learn more about [parameter tokens](https://guacamole.apache.org/doc/gug/configuring-guacamole.html#connection-configuration) \n\n \n# Troubleshooting and Logs\n\nViewing Traefik Logs\n```console\ncd /srv/workfromhome-with-docker\ndocker-compose logs -f --tail=1000 traefik\n```\n\nViewing Guacamole Logs\n```console\ncd /srv/workfromhome-with-docker\ndocker-compose logs -f --tail=1000 guacamole\n```\n\nViewing all Logs\n```console\ncd /srv/workfromhome-with-docker\ndocker-compose logs -f --tail=1000 \n```\n\n   \n# References and documentation\n\n[Guacamole User Guide](https://guacamole.apache.org/doc/gug/users-guide.html)  \n[Traefik Documentation](https://docs.traefik.io)\n\n\n# Disclaimer \n\nUse at your own risk.  \nThis is not a solution which scales for thousands of users.   \nDepending on your internet connection this is perfectly fine for 50+ users with a single Ubuntu machine.","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fandif888%2Fworkfromhome-with-docker","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fandif888%2Fworkfromhome-with-docker","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fandif888%2Fworkfromhome-with-docker/lists"}