Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Update README.md examples for network, labels #81

Open
wants to merge 1 commit into
base: develop
Choose a base branch
from
Open

Update README.md examples for network, labels #81

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
96 changes: 69 additions & 27 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -12,7 +12,7 @@ This image(s) is part of the [Docksal](http://docksal.io) image library.
- Stack stopping after a given period of inactivity
- Stack cleanup after a given period of inactivity

On-demand start and inactivity stop/cleanup features are the key components used by [Docksal Sandbox Server](https://github.com/docksal/sandbox-server).
On-demand start and inactivity stop/cleanup features are the key components used by [Docksal Sandbox Server](https://github.com/docksal/sandbox-server).

## Usage

Expand All @@ -25,13 +25,19 @@ docker run -d --name docksal-vhost-proxy --label "io.docksal.group=system" --res
docksal/vhost-proxy
```

## Container configuration
## Container configuration

Proxy reads routing settings from container labels.
Required labels for this VHost Proxy are `io.docksal.project-root` and `io.docksal.virtual-host`.

Proxy reads routing settings from container labels. The following labels are supported:

`io.docksal.project-root`

Project root. Supports CI/CD scenarios with the cleanup job (see [Advanced proxy configuration below](#advanced-proxy-configuration)) and project root volumes can be automatically un-mounted when not set to permanent.

`io.docksal.virtual-host`

Virtual host mapping. Supports any domain (but does not handle DNS), multiple values separated by commas, wildcard
Virtual host mapping. Supports any domain (but does not handle DNS), multiple values separated by commas, wildcard
sub-domains.

Example: `io.docksal.virtual-host=example1.com,*.example2.com`
Expand All @@ -40,14 +46,15 @@ Example: `io.docksal.virtual-host=example1.com,*.example2.com`
`io.docksal.virtual-port`

Virtual port mapping. Useful when a container exposes an non-default HTTP port (other than port `80`).
Only supports HTTP target services, single value.
Only supports HTTP target services, single value.

Example: `io.docksal.virtual-port=3000`

### Example: Routing to a standalone container

Routing `http(s)://myapp.example.com` to a standalone container listening on port `2580` (HTTP).

docker command
```bash
# Start a standalone container
$ docker run -d --name=http-echo \
Expand All @@ -60,7 +67,7 @@ $ docker run -d --name=http-echo \
$ DOCKER_HOST=192.168.64.100
$ curl --header "Host: myapp.example.com" http://${DOCKER_HOST}
Hello world: standalone
```
```

### Example: Routing to a container in a Docker Compose project stack

Expand Down Expand Up @@ -94,38 +101,73 @@ $ docker-compose -p myproject up -d
# Verify
$ curl http://myproject.docksal.site
"Hello world: docker-compose"
```
```

Notice that we used `myproject.docksal.site` in this example and did not project the `Host` header in the curl command.
`*.docksal.site` domains are automatically resolved to `192.168.64.100` (Docksal's canonical IP address).

You can use an arbitrary domain, but then you'll have to handle the DNS for that domain.
docker run -d --name=myapp_nodejs \
-v $(pwd):/app \
--label=com.docker.compose.project=myapp
--label=io.docksal.project-root=$(pwd) \
--label=io.docksal.virtual-host=myapp.example.com \
--label=io.docksal.virtual-port=3000 \
--network=myapp_default \
--expose 3000 \
node:alpine \
node /app/index.js
```

docker compose `myapp/docker-compose.yml`
```yaml
---

version: "3"
networks:
docksal_network:
external:
name: myapp_default

services:
web:
command: "node /app/index.js"
image: node:alpine
volumes:
- "./:/app"
labels:
- "io.docksal.project-root=${PWD}"
- "io.docksal.virtual-host=myapp.example.com"
- "io.docksal.virtual-port=3000"
networks:
- docksal_network
```

## Advanced proxy configuration

These advanced settings can be used in CI sandbox environments and help keep the resource usage down by stopping
These advanced settings can be used in CI sandbox environments and help keep the resource usage down by stopping
Docksal project containers after a period of inactivity.

Projects are automatically restarted upon a new HTTP request (unless `PROJECT_AUTOSTART` is set to `0`, see below).

See [Docksal Sandbox Server](https://github.com/docksal/sandbox-server) for the CI sandbox use case.

See [services.yml](https://github.com/docksal/docksal/blob/develop/stacks/services.yml) in the [docksal/docksal](https://github.com/docksal/docksal)
See [services.yml](https://github.com/docksal/docksal/blob/develop/stacks/services.yml) in the [docksal/docksal](https://github.com/docksal/docksal)
repo for an extensive list of examples of how docksal/vhost-proxy is used in Docksal.

`PROJECT_INACTIVITY_TIMEOUT`

Defines the timeout (e.g. 0.5h) of inactivity after which the project stack will be stopped.
Defines the timeout (e.g. 0.5h) of inactivity after which the project stack will be stopped.
This option is inactive by default (set to `0`).

`PROJECT_DANGLING_TIMEOUT`

**WARNING: This is a destructive option. Use at your own risk!**

Defines the timeout (e.g. 168h) of inactivity after which the project stack and code base will be entirely wiped out from the host.
Defines the timeout (e.g. 168h) of inactivity after which the project stack and code base will be entirely wiped out from the host.
This option is inactive by default (set to `0`).

For the cleanup job to work, proxy needs access to the projects directory on the host.
For the cleanup job to work, proxy needs access to the projects directory on the host.
Create a Docker bind volume pointing to the directory where projects are stored:

```
Expand All @@ -135,7 +177,7 @@ docker volume create --name docksal_projects --opt type=none --opt device=$PROJE

then pass it using `-v docksal_projects:/projects` in `docker run` command.

Example (extra configuration in the middle):
Example (extra configuration in the middle):

```bash
docker run -d --name docksal-vhost-proxy --label "io.docksal.group=system" --restart=always --privileged --userns=host \
Expand All @@ -145,7 +187,7 @@ docker run -d --name docksal-vhost-proxy --label "io.docksal.group=system" --res
-e PROJECT_INACTIVITY_TIMEOUT="${PROJECT_INACTIVITY_TIMEOUT:-0}" \
-e PROJECT_DANGLING_TIMEOUT="${PROJECT_DANGLING_TIMEOUT:-0}" \
-v docksal_projects:/projects \

-v /var/run/docker.sock:/var/run/docker.sock \
docksal/vhost-proxy
```
Expand All @@ -155,7 +197,7 @@ docker run -d --name docksal-vhost-proxy --label "io.docksal.group=system" --res
It is possible to protect certain projects/containers from being automatically removed after `PROJECT_DANGLING_TIMEOUT`.

Projects/containers with the `io.docksal.permanent=true` label are considered permanent are skipped during the cleanup.
When running the default Docksal stack, this label can be set with `SANDBOX_PERMANENT=true` in `docksal.env` (or an
When running the default Docksal stack, this label can be set with `SANDBOX_PERMANENT=true` in `docksal.env` (or an
environment specific equivalent, e.g. `docksal-ci.env`).

Note: permanent projects will still be put into hibernation according to `PROJECT_INACTIVITY_TIMEOUT`.
Expand All @@ -166,12 +208,12 @@ Setting this variable to `0` will disable autostart projects by visiting project

## Default and custom certs for HTTPS

The default server cert is a self-signed cert for `*.docksal`. It allows an HTTPS connection to be established, but will
make browsers complain that the cert is not valid. If that's not acceptable, you can use a valid custom cert.
The default server cert is a self-signed cert for `*.docksal`. It allows an HTTPS connection to be established, but will
make browsers complain that the cert is not valid. If that's not acceptable, you can use a valid custom cert.

To use custom certs, mount a folder with certs to `/etc/certs/custom`. Certs are looked up by virtual host name.
To use custom certs, mount a folder with certs to `/etc/certs/custom`. Certs are looked up by virtual host name.

E.g., cert and key for `example.com` (or `*.example.com`) are expected in:
E.g., cert and key for `example.com` (or `*.example.com`) are expected in:

```
/etc/certs/custom/example.com.crt
Expand All @@ -187,21 +229,21 @@ Example: for `io.docksal.cert-name=shared` the following cert/key will be used:
/etc/certs/custom/shared.key
```

When multiple domain values are set in `io.docksal.virtual-host`, the first one is considered the primary one and
used for certificate lookup. You can also always point to a specific cert with `io.docksal.cert-name`.
When multiple domain values are set in `io.docksal.virtual-host`, the first one is considered the primary one and
used for certificate lookup. You can also always point to a specific cert with `io.docksal.cert-name`.

When projects are (re)started over HTTPS, the default virtual host config kicks in first. It uses the default self-signed
cert, which would trigger a browser warning, even though the actual virtual host is then served using a valid custom
cert. To overcome this issue, you can specify the default custom cert name using the `DEFAULT_CERT` environment variable.
When projects are (re)started over HTTPS, the default virtual host config kicks in first. It uses the default self-signed
cert, which would trigger a browser warning, even though the actual virtual host is then served using a valid custom
cert. To overcome this issue, you can specify the default custom cert name using the `DEFAULT_CERT` environment variable.

You can use a single domain or a shared (SNI) cert, just like with other custom certs.

Example: `DEFAULT_CERT=example.com` or `DEFAULT_CERT=shared`
Example: `DEFAULT_CERT=example.com` or `DEFAULT_CERT=shared`


## Logging and debugging

The following container environment variables can be used to enabled various logging options (disabled by default).
The following container environment variables can be used to enabled various logging options (disabled by default).

`ACCESS_LOG` - Set to `1` to enable access logging.
`DEBUG_LOG` - Set to `1` to enable debug logging.
Expand All @@ -212,7 +254,7 @@ Check logs with `docker logs docksal-vhost-proxy`.

## Variable mapping for Docksal

When using this image with Docksal (99% of cases), settings for `vhost-proxy` are set via `$HOME/.docksal/docksal.env`.
When using this image with Docksal (99% of cases), settings for `vhost-proxy` are set via `$HOME/.docksal/docksal.env`.

The following variable mappings should be applied:

Expand Down