{"id":195,"date":"2026-07-28T06:16:47","date_gmt":"2026-07-28T06:16:47","guid":{"rendered":"https:\/\/www.miniamju.com\/index.php\/apache-guacamole-part-1-building-the-remote-access-container\/"},"modified":"2026-07-28T06:16:47","modified_gmt":"2026-07-28T06:16:47","slug":"apache-guacamole-part-1-building-the-remote-access-container","status":"publish","type":"post","link":"https:\/\/www.miniamju.com\/index.php\/apache-guacamole-part-1-building-the-remote-access-container\/","title":{"rendered":"Apache Guacamole Part 1: Building the Remote Access Container"},"content":{"rendered":"

Part 1 of 3: container build, application stack, and authentication baseline.<\/em><\/p>\n

Apache Guacamole provides remote desktop access through an ordinary web
\nbrowser. The goal of this series is to build a small self-hosted gateway that
\ncan reach approved private machines without exposing RDP or other remote
\ndesktop ports directly to the internet.<\/p>\n

This first part creates the gateway in an unprivileged Ubuntu 24.04 LXD system
\ncontainer. Docker Compose runs Guacamole, guacd<\/code>, and PostgreSQL inside that
\ncontainer. TOTP protects the Guacamole login, and separate Docker networks
\nlimit which components can reach the database, web application, and eventual
\nremote desktop targets.<\/p>\n

The complete series is:<\/p>\n

    \n
  1. Part 1:<\/strong> build and validate the private Guacamole container;<\/li>\n
  2. Part 2:<\/strong> publish the gateway securely through Nginx and TLS;<\/li>\n
  3. Part 3:<\/strong> allow and test a least-privilege Windows RDP connection.<\/li>\n<\/ol>\n

    The examples use fictional private addresses and generic names. No real
    \nhostnames, usernames, credentials, or infrastructure identifiers are included.<\/p>\n

    \n

    Why build it this way?<\/strong> Guacamole is an authentication gateway with access
    \nto private systems. Keeping it in its own unprivileged container, isolating
    \nits database, and allowing only explicitly approved network paths reduces the
    \nimpact of either a configuration mistake or an application compromise.<\/p>\n<\/blockquote>\n

    Architecture<\/h2>\n

    The completed stack uses:<\/p>\n

      \n
    • an unprivileged Ubuntu 24.04 LXD container;<\/li>\n
    • Docker Engine and Docker Compose inside LXD;<\/li>\n
    • Apache Guacamole and guacd<\/code> 1.6.0;<\/li>\n
    • PostgreSQL 17;<\/li>\n
    • TOTP second-factor authentication;<\/li>\n
    • an internal Docker backend network;<\/li>\n
    • a separate guacd<\/code> remote-access network;<\/li>\n
    • persistent PostgreSQL data and RDP certificate trust;<\/li>\n
    • one private HTTP listener for the later Nginx reverse proxy.<\/li>\n<\/ul>\n

      PostgreSQL and port 4822 on guacd<\/code> are never published.<\/p>\n

      Internet access is added in Part 2\n                 |\n                 v\n       private HTTP listener\n                 |\n        +--------+---------+\n        | Guacamole web    |\n        +--------+---------+\n                 |\n        internal Docker network\n          |              |\n          v              v\n     PostgreSQL        guacd\n                         |\n                controlled target network\n                         |\n                approved VMs in Part 3\n<\/code><\/pre>\n
      The distinction between the two Docker networks matters. The internal backend
      \nlets the application components communicate but has no route to the LAN. The
      \ncontrolled target network gives only guacd<\/code> a stable source address that can
      \nlater be matched by endpoint-specific firewall rules.<\/p>\n
      1. Choose Local Values<\/h2>\n
      The examples use neutral private addresses and generic resource names. Replace
      \nthem with values suitable for the local environment:<\/p>\n
      INSTANCE=guacamole-gateway\nSTORAGE_POOL=lxd-pool\nLAN_BRIDGE=br0\nGUAC_IP=10.20.30.223\nGATEWAY_IP=10.20.30.1\nPROXY_IP=10.20.30.220\n<\/code><\/pre>\n
      The remote-access Docker subnet must not overlap any LAN, VPN, LXD, libvirt,
      \nor existing Docker network. An overlap can send traffic toward the wrong
      \ninterface or make a private target unreachable. This guide uses:<\/p>\n
      172.20.0.0\/24\n<\/code><\/pre>\n
      Check the candidate container address from the LXD host:<\/p>\n
      ping -c 2 "$GUAC_IP"\nip neigh show "$GUAC_IP"\n<\/code><\/pre>\n
      Expected result:<\/p>\n
      no ICMP response\nno valid neighbour entry\n<\/code><\/pre>\n
      Also reserve or exclude the address in DHCP before assigning it statically.<\/p>\n
      2. Create the LXD Container<\/h2>\n
      The container receives two CPUs and 2 GiB of memory. These are limits, not
      \npermanently reserved resources: the host scheduler can still use the same CPU
      \ncapacity for other workloads when Guacamole is idle.<\/p>\n
      Run on the LXD host:<\/p>\n
      lxc init ubuntu:24.04 "$INSTANCE" \\\n  --storage "$STORAGE_POOL" \\\n  --config limits.cpu=2 \\\n  --config limits.memory=2GiB \\\n  --config security.nesting=true \\\n  --config security.syscalls.intercept.mknod=true \\\n  --config security.syscalls.intercept.setxattr=true \\\n  --config boot.autostart=true\n\nlxc config device set "$INSTANCE" root size 20GiB\n\nlxc config device override "$INSTANCE" eth0 \\\n  nictype=bridged \\\n  parent="$LAN_BRIDGE" \\\n  name=eth0\n\nlxc config set "$INSTANCE" cloud-init.network-config "$(cat <<EOF\nversion: 2\nethernets:\n  eth0:\n    dhcp4: false\n    addresses:\n      - ${GUAC_IP}\/24\n    routes:\n      - to: default\n        via: ${GATEWAY_IP}\n    nameservers:\n      addresses:\n        - ${GATEWAY_IP}\n        - 1.1.1.1\nEOF\n)"\n<\/code><\/pre>\n
      Inspect the complete configuration before starting:<\/p>\n
      lxc config show "$INSTANCE" --expanded\n<\/code><\/pre>\n
      Confirm:<\/p>\n
      limits.cpu: "2"\nlimits.memory: 2GiB\nsecurity.nesting: "true"\nsecurity.syscalls.intercept.mknod: "true"\nsecurity.syscalls.intercept.setxattr: "true"\nroot disk size: 20GiB\neth0: bridged to the intended LAN bridge\n<\/code><\/pre>\n
      Start the container:<\/p>\n
      lxc start "$INSTANCE"\nlxc exec "$INSTANCE" -- cloud-init status --wait\n<\/code><\/pre>\n
      Expected final cloud-init state:<\/p>\n
      status: done\n<\/code><\/pre>\n
      3. Validate the Container<\/h2>\n
      Check identity, networking, storage, and memory:<\/p>\n
      lxc exec "$INSTANCE" -- hostnamectl\nlxc exec "$INSTANCE" -- ip -brief address\nlxc exec "$INSTANCE" -- ip route\nlxc exec "$INSTANCE" -- ping -c 2 "$GATEWAY_IP"\nlxc exec "$INSTANCE" -- ping -c 2 "$PROXY_IP"\nlxc exec "$INSTANCE" -- getent hosts archive.ubuntu.com\nlxc exec "$INSTANCE" -- curl -I https:\/\/archive.ubuntu.com\nlxc exec "$INSTANCE" -- df -hT \/\nlxc exec "$INSTANCE" -- free -h\n<\/code><\/pre>\n
      Required results:<\/p>\n
        \n
      • Ubuntu 24.04 is reported;<\/li>\n
      • eth0<\/code> has the chosen static address;<\/li>\n
      • the default route uses the chosen gateway;<\/li>\n
      • the gateway and reverse proxy answer;<\/li>\n
      • DNS resolves;<\/li>\n
      • outbound HTTPS returns a successful response;<\/li>\n
      • the root filesystem reflects the intended quota;<\/li>\n
      • the memory limit is approximately 2 GiB.<\/li>\n<\/ul>\n
        Stop here if the static route, DNS, or outbound HTTPS checks fail.<\/p>\n
        4. Install Docker Engine<\/h2>\n
        Open an interactive root console:<\/p>\n
        lxc exec "$INSTANCE" -- bash\n<\/code><\/pre>\n
        The remaining commands are entered directly at the container prompt.<\/p>\n
        Update Ubuntu:<\/p>\n
        set -euo pipefail\nexport DEBIAN_FRONTEND=noninteractive\n\napt-get update\napt-get -y full-upgrade\napt-get -y install ca-certificates curl\n<\/code><\/pre>\n
        Configure Docker's official Ubuntu repository:<\/p>\n
        install -m 0755 -d \/etc\/apt\/keyrings\n\ncurl -fsSL https:\/\/download.docker.com\/linux\/ubuntu\/gpg \\\n  -o \/etc\/apt\/keyrings\/docker.asc\n\nchmod a+r \/etc\/apt\/keyrings\/docker.asc\n\n. \/etc\/os-release\n\nprintf "%s\\n" \\\n  "deb [arch=$(dpkg --print-architecture) signed-by=\/etc\/apt\/keyrings\/docker.asc] https:\/\/download.docker.com\/linux\/ubuntu ${UBUNTU_CODENAME:-$VERSION_CODENAME} stable" \\\n  > \/etc\/apt\/sources.list.d\/docker.list\n\napt-get update\n<\/code><\/pre>\n
        Install and start Docker:<\/p>\n
        apt-get -y install \\\n  docker-ce \\\n  docker-ce-cli \\\n  containerd.io \\\n  docker-buildx-plugin \\\n  docker-compose-plugin\n\nsystemctl enable --now docker\n<\/code><\/pre>\n
        Validate the installation:<\/p>\n
        docker version\ndocker compose version\nsystemctl is-enabled docker\nsystemctl is-active docker\ndocker info --format "Storage driver: {{.Driver}}"\ndocker info --format "{{json .DriverStatus}}"\ndocker info --format "{{.DockerRootDir}}"\ndocker info --format "{{json .SecurityOptions}}"\n<\/code><\/pre>\n
        Expected key results:<\/p>\n
        Docker client and server versions are shown\nDocker Compose version is shown\nenabled\nactive\nstorage uses overlayfs, overlay2, or an overlay snapshotter\n\/var\/lib\/docker\nAppArmor and seccomp are listed\n<\/code><\/pre>\n
        Do not continue if Docker reports the vfs<\/code> storage driver.<\/p>\n
        Exit to the LXD host and take a rollback snapshot:<\/p>\n
        exit\nlxc snapshot "$INSTANCE" post-docker-baseline\nlxc exec "$INSTANCE" -- bash\n<\/code><\/pre>\n
        5. Prepare Application Files<\/h2>\n
        Application state is separated from the Compose definition. PostgreSQL data
        \nand FreeRDP trust information live in named volumes, while the database
        \npassword is supplied through a file-backed Docker secret. This keeps the
        \npassword out of the Compose file and normal container environment output.<\/p>\n
        Create the application, initialization, and secret directories:<\/p>\n
        GUAC_IP=10.20.30.223\n\ninstall -d -m 0750 \/opt\/guacamole\/init\ninstall -d -m 0700 \/opt\/guacamole\/secrets\ncd \/opt\/guacamole\n<\/code><\/pre>\n
        Generate a newline-free database password without displaying it:<\/p>\n
        umask 077\n\nopenssl rand -base64 48 | tr -d '\\r\\n' \\\n  > secrets\/postgres_password\n\nchmod 0644 secrets\/postgres_password\n<\/code><\/pre>\n
        The file is readable because the Guacamole container runs as a non-root user,
        \nbut its parent directory remains accessible only to root.<\/p>\n
        Validate only the length:<\/p>\n
        test "$(wc -c < secrets\/postgres_password)" -eq 64 &&\n  echo "PostgreSQL password file is valid"\n<\/code><\/pre>\n
        Expected:<\/p>\n
        PostgreSQL password file is valid\n<\/code><\/pre>\n
        Pull fixed image versions:<\/p>\n
        docker pull guacamole\/guacamole:1.6.0\ndocker pull guacamole\/guacd:1.6.0\ndocker pull postgres:17-alpine\n<\/code><\/pre>\n
        Each pull must finish successfully with a digest or an up-to-date message.<\/p>\n
        Generate the matching PostgreSQL schema:<\/p>\n
        docker run --rm \\\n  guacamole\/guacamole:1.6.0 \\\n  \/opt\/guacamole\/bin\/initdb.sh --postgresql \\\n  > init\/001-guacamole.sql\n\nchmod 0644 init\/001-guacamole.sql\n\ntest -s init\/001-guacamole.sql &&\n  echo "Guacamole database schema generated"\n\ngrep -c 'CREATE TABLE' init\/001-guacamole.sql\n<\/code><\/pre>\n
        Expected:<\/p>\n
        Guacamole database schema generated\na non-zero CREATE TABLE count\n<\/code><\/pre>\n
        6. Check Docker Subnets<\/h2>\n
        Before assigning the controlled guacd<\/code> subnet:<\/p>\n
        ip -4 route\n\ndocker network inspect $(docker network ls -q) \\\n  --format '{{.Name}}: {{range .IPAM.Config}}{{.Subnet}} {{end}}'\n<\/code><\/pre>\n
        Confirm that 172.20.0.0\/24<\/code> does not appear in either result. Select another
        \nunused private subnet if it does.<\/p>\n
        7. Create the Compose Stack<\/h2>\n
        The Compose file deliberately gives each component only the networks and
        \npublished ports it needs:<\/p>\n
          \n
        • PostgreSQL uses only the internal backend;<\/li>\n
        • guacd<\/code> uses the backend and controlled target network;<\/li>\n
        • the Guacamole web application uses the backend and frontend;<\/li>\n
        • only the web application publishes a private LAN listener.<\/li>\n<\/ul>\n
          Create a local environment file using the container's private LAN address:<\/p>\n
          cat > .env <<EOF\nGUACAMOLE_BIND_ADDRESS=${GUAC_IP}\nEOF\n\nchmod 0640 .env\n<\/code><\/pre>\n
          Create compose.yaml<\/code>:<\/p>\n
          cat > compose.yaml <<'EOF'\nname: guacamole\n\nservices:\n  postgres:\n    image: postgres:17-alpine\n    container_name: guacamole-postgres\n    restart: unless-stopped\n    environment:\n      POSTGRES_DB: guacamole_db\n      POSTGRES_USER: guacamole_user\n      POSTGRES_PASSWORD_FILE: \/run\/secrets\/postgres_password\n    secrets:\n      - postgres_password\n    volumes:\n      - postgres_data:\/var\/lib\/postgresql\/data\n      - .\/init\/001-guacamole.sql:\/docker-entrypoint-initdb.d\/001-guacamole.sql:ro\n    networks:\n      - backend\n    healthcheck:\n      test:\n        - CMD-SHELL\n        - pg_isready -U guacamole_user -d guacamole_db\n      interval: 10s\n      timeout: 5s\n      retries: 10\n      start_period: 20s\n    security_opt:\n      - no-new-privileges:true\n\n  guacd:\n    image: guacamole\/guacd:1.6.0\n    container_name: guacamole-guacd\n    restart: unless-stopped\n    volumes:\n      - guacd_freerdp:\/home\/guacd\/.config\/freerdp\n    networks:\n      backend:\n      remote_access:\n        ipv4_address: 172.20.0.2\n    security_opt:\n      - no-new-privileges:true\n\n  guacamole:\n    image: guacamole\/guacamole:1.6.0\n    container_name: guacamole-web\n    restart: unless-stopped\n    depends_on:\n      postgres:\n        condition: service_healthy\n      guacd:\n        condition: service_started\n    environment:\n      WEBAPP_CONTEXT: ROOT\n      GUACD_HOSTNAME: guacd\n      GUACD_PORT: "4822"\n      POSTGRESQL_ENABLED: "true"\n      POSTGRESQL_HOSTNAME: postgres\n      POSTGRESQL_PORT: "5432"\n      POSTGRESQL_DATABASE: guacamole_db\n      POSTGRESQL_USERNAME: guacamole_user\n      POSTGRESQL_PASSWORD_FILE: \/run\/secrets\/postgres_password\n      TOTP_ENABLED: "true"\n      REMOTE_IP_VALVE_ENABLED: "true"\n      REMOTE_IP_VALVE_REMOTE_IP_HEADER: x-forwarded-for\n      REMOTE_IP_VALVE_PROTOCOL_HEADER: x-forwarded-proto\n      REMOTE_IP_VALVE_PROTOCOL_HEADER_HTTPS_VALUE: https\n      REMOTE_IP_VALVE_HTTP_SERVER_PORT: "80"\n      REMOTE_IP_VALVE_HTTPS_SERVER_PORT: "443"\n    secrets:\n      - postgres_password\n    ports:\n      - "${GUACAMOLE_BIND_ADDRESS}:8080:8080"\n    networks:\n      - frontend\n      - backend\n    security_opt:\n      - no-new-privileges:true\n\nsecrets:\n  postgres_password:\n    file: .\/secrets\/postgres_password\n\nvolumes:\n  postgres_data:\n  guacd_freerdp:\n\nnetworks:\n  frontend:\n  backend:\n    internal: true\n  remote_access:\n    name: guacamole_remote_access\n    driver: bridge\n    driver_opts:\n      com.docker.network.bridge.name: br-guac-remote\n    ipam:\n      config:\n        - subnet: 172.20.0.0\/24\n          gateway: 172.20.0.1\nEOF\n<\/code><\/pre>\n
          The network roles are:<\/p>\n\n\n\n\n\n\n\n
          Network<\/th>\nAttached services<\/th>\nPurpose<\/th>\n<\/tr>\n<\/thead>\n
          frontend<\/code><\/td>\nGuacamole web<\/td>\npublished private HTTP listener<\/td>\n<\/tr>\n
          backend<\/code><\/td>\nPostgreSQL, guacd<\/code>, Guacamole web<\/td>\ninternal application traffic<\/td>\n<\/tr>\n
          remote_access<\/code><\/td>\nguacd<\/code> only<\/td>\ncontrol point for outbound remote protocols<\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n
          The remote-access network is created now, but its destination allowlist is
          \nendpoint-dependent. Do not configure VM connections until the firewall step in
          \nThe controlled remote_access<\/code> network is created now, but no target is
          \nreachable through it until Part 3 adds an explicit firewall allowlist.<\/p>\n
          8. Validate and Start<\/h2>\n
          The first start creates the database schema and named volumes. The checks below
          \nconfirm both application health and the network boundaries before any public
          \nDNS or reverse proxy is introduced.<\/p>\n
          Validate the resolved Compose model:<\/p>\n
          docker compose config\n<\/code><\/pre>\n
          Review the output and confirm:<\/p>\n