{"id":18400452,"url":"https://github.com/docksal/service-vhost-proxy","last_synced_at":"2025-07-24T13:07:19.753Z","repository":{"id":11893586,"uuid":"69355273","full_name":"docksal/service-vhost-proxy","owner":"docksal","description":"Virtual host proxy service image for Docksal","archived":false,"fork":false,"pushed_at":"2022-03-25T23:01:29.000Z","size":1762,"stargazers_count":7,"open_issues_count":9,"forks_count":14,"subscribers_count":7,"default_branch":"develop","last_synced_at":"2024-10-29T21:53:18.321Z","etag":null,"topics":["proxy-container"],"latest_commit_sha":null,"homepage":"http://docksal.io","language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/docksal.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2016-09-27T12:41:32.000Z","updated_at":"2021-11-24T20:23:54.000Z","dependencies_parsed_at":"2022-08-07T06:16:38.303Z","dependency_job_id":null,"html_url":"https://github.com/docksal/service-vhost-proxy","commit_stats":null,"previous_names":[],"tags_count":21,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/docksal%2Fservice-vhost-proxy","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/docksal%2Fservice-vhost-proxy/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/docksal%2Fservice-vhost-proxy/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/docksal%2Fservice-vhost-proxy/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/docksal","download_url":"https://codeload.github.com/docksal/service-vhost-proxy/tar.gz/refs/heads/develop","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247607739,"owners_count":20965945,"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":["proxy-container"],"created_at":"2024-11-06T02:33:29.773Z","updated_at":"2025-04-07T06:33:25.303Z","avatar_url":"https://github.com/docksal.png","language":"Shell","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Virtual host proxy Docker image for Docksal\n\nAutomated HTTP/HTTPS virtual host proxy and container supervisor for Docksal.\n\nThis image(s) is part of the [Docksal](http://docksal.io) image library.\n\n## Features\n\n- HTTP/HTTPS and HTTP/2 virtual host routing\n- Supports Docker Compose based stacks as well as standalone containers (`docker run ...`)\n- On-demand stack starting (upon HTTP/HTTPS request)\n- Stack stopping after a given period of inactivity\n- Stack cleanup after a given period of inactivity\n\nOn-demand start and inactivity stop/cleanup features are the key components used by [Docksal Sandbox Server](https://github.com/docksal/sandbox-server). \n\n## Usage\n\nStart the proxy container:\n\n```bash\ndocker run -d --name docksal-vhost-proxy --label \"io.docksal.group=system\" --restart=always --privileged --userns=host \\\n    -p \"${DOCKSAL_VHOST_PROXY_PORT_HTTP:-80}\":80 -p \"${DOCKSAL_VHOST_PROXY_PORT_HTTPS:-443}\":443 \\\n    -v /var/run/docker.sock:/var/run/docker.sock \\\n    docksal/vhost-proxy\n```\n\n## Container configuration \n\nProxy reads routing settings from container labels. \n\n`io.docksal.virtual-host`\n\nVirtual host mapping. Supports any domain (but does not handle DNS), multiple values separated by commas, wildcard \nsub-domains.\n\nExample: `io.docksal.virtual-host=example1.com,*.example2.com`\n\n\n`io.docksal.virtual-port`\n\nVirtual port mapping. Useful when a container exposes an non-default HTTP port (other than port `80`).\nOnly supports HTTP target services, single value.  \n\nExample: `io.docksal.virtual-port=3000`\n\n### Example: Routing to a standalone container\n\nRouting `http(s)://myapp.example.com` to a standalone container listening on port `2580` (HTTP).\n\n```bash\n# Start a standalone container\n$ docker run -d --name=http-echo \\\n\t--label=io.docksal.virtual-host=myapp.example.com \\\n\t--label=io.docksal.virtual-port=2580 \\\n\t--expose 2580 \\\n\thashicorp/http-echo:0.2.3 -listen=:2580 -text=\"Hello world: standalone\"\n\n# Verify\n$ DOCKER_HOST=192.168.64.100\n$ curl --header \"Host: myapp.example.com\" http://${DOCKER_HOST}\nHello world: standalone\n``` \n\n### Example: Routing to a container in a Docker Compose project stack\n\nRouting `http(s)://myproject.example.com` to a container in a Docker Compose stack listening on port `2580` (HTTP).\n\n```bash\n$ cat docker-compose.yaml\nversion: \"3\"\n\n# Uncomment if you want this stack to attach to an existing network (e.g., another Docksal project network)\n#networks:\n#  default:\n#    external: true\n#    name: \u003cproject-name\u003e_default\n\nservices:\n  web:\n    image: hashicorp/http-echo:0.2.3\n    # Comment out if using a specific existing network\n    network_mode: bridge # Use the default shared 'bridge' network\n    expose:\n      - 2580\n    labels:\n      - \"io.docksal.virtual-host=myproject.docksal.site\"\n      - \"io.docksal.virtual-port=2580\"\n    command: ['-listen=:2580', '-text=\"Hello world: docker-compose\"']\n\n$ docker-compose -p myproject up -d\n...\n\n# Verify\n$ curl http://myproject.docksal.site\n\"Hello world: docker-compose\"\n``` \n\nNotice that we used `myproject.docksal.site` in this example and did not project the `Host` header in the curl command.\n`*.docksal.site` domains are automatically resolved to `192.168.64.100` (Docksal's canonical IP address).\n\nYou can use an arbitrary domain, but then you'll have to handle the DNS for that domain.\n\n## Advanced proxy configuration\n\nThese advanced settings can be used in CI sandbox environments and help keep the resource usage down by stopping \nDocksal project containers after a period of inactivity.\n\nProjects are automatically restarted upon a new HTTP request (unless `PROJECT_AUTOSTART` is set to `0`, see below).\n\nSee [Docksal Sandbox Server](https://github.com/docksal/sandbox-server) for the CI sandbox use case.\n\nSee [services.yml](https://github.com/docksal/docksal/blob/develop/stacks/services.yml) in the [docksal/docksal](https://github.com/docksal/docksal) \nrepo for an extensive list of examples of how docksal/vhost-proxy is used in Docksal.\n\n`PROJECT_INACTIVITY_TIMEOUT`\n\nDefines the timeout (e.g. 0.5h) of inactivity after which the project stack will be stopped.  \nThis option is inactive by default (set to `0`).\n\n`PROJECT_DANGLING_TIMEOUT`\n\n**WARNING: This is a destructive option. Use at your own risk!**\n\nDefines the timeout (e.g. 168h) of inactivity after which the project stack and code base will be entirely wiped out from the host.  \nThis option is inactive by default (set to `0`).\n\nFor the cleanup job to work, proxy needs access to the projects directory on the host.  \nCreate a Docker bind volume pointing to the directory where projects are stored:\n\n```\ndocker volume create --name docksal_projects --opt type=none --opt device=$PROJECTS_ROOT --opt o=bind\n\n```\n\nthen pass it using `-v docksal_projects:/projects` in `docker run` command.\n\nExample (extra configuration in the middle): \n\n```bash\ndocker run -d --name docksal-vhost-proxy --label \"io.docksal.group=system\" --restart=always --privileged --userns=host \\\n    -p \"${DOCKSAL_VHOST_PROXY_PORT_HTTP:-80}\":80 -p \"${DOCKSAL_VHOST_PROXY_PORT_HTTPS:-443}\":443 \\\n    -e PROJECT_INACTIVITY_TIMEOUT=\"${PROJECT_INACTIVITY_TIMEOUT:-0}\" \\\n\n    -e PROJECT_INACTIVITY_TIMEOUT=\"${PROJECT_INACTIVITY_TIMEOUT:-0}\" \\\n    -e PROJECT_DANGLING_TIMEOUT=\"${PROJECT_DANGLING_TIMEOUT:-0}\" \\\n    -v docksal_projects:/projects \\\n    \n    -v /var/run/docker.sock:/var/run/docker.sock \\\n    docksal/vhost-proxy\n```\n\n`io.docksal.permanent=true`\n\nIt is possible to protect certain projects/containers from being automatically removed after `PROJECT_DANGLING_TIMEOUT`.\n\nProjects/containers with the `io.docksal.permanent=true` label are considered permanent are skipped during the cleanup.\nWhen running the default Docksal stack, this label can be set with `SANDBOX_PERMANENT=true` in `docksal.env` (or an \nenvironment specific equivalent, e.g. `docksal-ci.env`).\n\nNote: permanent projects will still be put into hibernation according to `PROJECT_INACTIVITY_TIMEOUT`.\n\n`PROJECT_AUTOSTART`\n\nSetting this variable to `0` will disable autostart projects by visiting project url. This option is active by default (set to `1`).\n\n## Default and custom certs for HTTPS\n\nThe default server cert is a self-signed cert for `*.docksal`. It allows an HTTPS connection to be established, but will \nmake browsers complain that the cert is not valid. If that's not acceptable, you can use a valid custom cert. \n\nTo use custom certs, mount a folder with certs to `/etc/certs/custom`. Certs are looked up by virtual host name. \n\nE.g., cert and key for `example.com` (or `*.example.com`) are expected in: \n\n```\n/etc/certs/custom/example.com.crt\n/etc/certs/custom/example.com.key\n```\n\nShared certs (SNI) are also supported. Use `io.docksal.cert-name` label to set the cert name for a container.\n\nExample: for `io.docksal.cert-name=shared` the following cert/key will be used:\n\n```\n/etc/certs/custom/shared.crt\n/etc/certs/custom/shared.key\n```\n\nWhen multiple domain values are set in `io.docksal.virtual-host`, the first one is considered the primary one and \nused for certificate lookup. You can also always point to a specific cert with `io.docksal.cert-name`. \n\nWhen projects are (re)started over HTTPS, the default virtual host config kicks in first. It uses the default self-signed \ncert, which would trigger a browser warning, even though the actual virtual host is then served using a valid custom \ncert. To overcome this issue, you can specify the default custom cert name using the `DEFAULT_CERT` environment variable. \n\nYou can use a single domain or a shared (SNI) cert, just like with other custom certs.\n\nExample: `DEFAULT_CERT=example.com` or `DEFAULT_CERT=shared`  \n\n\n## Logging and debugging\n\nThe following container environment variables can be used to enabled various logging options (disabled by default). \n\n`ACCESS_LOG` - Set to `1` to enable access logging.\n`DEBUG_LOG` - Set to `1` to enable debug logging.\n`STATS_LOG` - Set to `1` to enable project stats logging.\n\nCheck logs with `docker logs docksal-vhost-proxy`.\n\n\n## Variable mapping for Docksal\n\nWhen using this image with Docksal (99% of cases), settings for `vhost-proxy` are set via `$HOME/.docksal/docksal.env`. \n\nThe following variable mappings should be applied:\n\n| Configuration variable        | Variable in `$HOME/.docksal/docksal.env`  |\n| ----------------------------- | ----------------------------------------  |\n| `ACCESS_LOG`                  | `DOCKSAL_VHOST_PROXY_ACCESS_LOG`          |\n| `DEBUG_LOG`                   | `DOCKSAL_VHOST_PROXY_DEBUG_LOG`           |\n| `STATS_LOG`                   | `DOCKSAL_VHOST_PROXY_STATS_LOG`           |\n| `PROJECT_INACTIVITY_TIMEOUT`  | `PROJECT_INACTIVITY_TIMEOUT`              |\n| `PROJECT_DANGLING_TIMEOUT`    | `PROJECT_DANGLING_TIMEOUT`                |\n| `DEFAULT_CERT`                | `DOCKSAL_VHOST_PROXY_DEFAULT_CERT`        |\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdocksal%2Fservice-vhost-proxy","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdocksal%2Fservice-vhost-proxy","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdocksal%2Fservice-vhost-proxy/lists"}