Repository: luisfarzati/localdots
Branch: master
Commit: 490fbf67b9c0
Files: 9
Total size: 8.3 KB

Directory structure:
gitextract_s762647g/

├── .dockerignore
├── Caddyfile
├── Dockerfile
├── LICENSE
├── README.md
├── caddy.d/
│   ├── hello.dev.example
│   └── whoami.localhost
├── docker-compose.yaml
└── start.sh

================================================
FILE CONTENTS
================================================

================================================
FILE: .dockerignore
================================================
LICENSE
README.md
docker-compose.yaml
caddy.d


================================================
FILE: Caddyfile
================================================
import /caddy.d/*


================================================
FILE: Dockerfile
================================================
FROM alpine:3
LABEL maintainer="Luis Farzati (lfarzati@gmail.com)"

ARG PLUGINS=
ARG CADDYFILE=/etc/Caddyfile
ARG CADDY_D=/caddy.d
ARG STEP_CLI_VERSION=0.13.3
ARG STEP_CA_VERSION=0.13.3
ARG STEP_BINPATH=/usr/local/bin
ARG STEPPATH=/caroot

ENV CADDYFILE=${CADDYFILE}
ENV CADDY_D=${CADDY_D}
ENV STEPPATH=${STEPPATH}
ENV LEGO_CA_CERTIFICATES=${STEPPATH}/certs/root_ca.crt
ENV CADDY_PIDFILE=/tmp/caddy.pid

EXPOSE 443

RUN apk add --no-cache \
  ca-certificates libcap curl inotify-tools grep jq \
  && rm -rf /var/cache/apk/* \
  && curl -fsSL -o - \
  "https://caddyserver.com/download/linux/amd64?plugins=${PLUGINS}&license=personal&telemetry=off" \
  | tar --no-same-owner -C /usr/bin/ -xz caddy \
  && curl -fsSL -o - \
  "https://github.com/smallstep/cli/releases/download/v${STEP_CLI_VERSION}/step_${STEP_CLI_VERSION}_linux_amd64.tar.gz" \
  | tar -xz --strip-components 2 -C ${STEP_BINPATH}  \
  && curl -fsSL -o - \
  "https://github.com/smallstep/certificates/releases/download/v${STEP_CA_VERSION}/step-certificates_${STEP_CA_VERSION}_linux_amd64.tar.gz" \
  | tar -zx --strip-components 2 -C ${STEP_BINPATH} \
  && chmod 0755 /usr/bin/caddy \
  && addgroup -S caddy  \
  && adduser -D -S -s /sbin/nologin -G caddy caddy  \
  && setcap cap_net_bind_service=+ep `readlink -f /usr/bin/caddy`  \
  && /usr/bin/caddy -version  \
  && mkdir -p ${CADDY_D} ${STEPPATH}  \
  && chown -R caddy ${STEPPATH}

COPY Caddyfile /etc/
COPY start.sh /

RUN chmod +x /start.sh

USER caddy

ENTRYPOINT ["/start.sh"]


================================================
FILE: LICENSE
================================================
Copyright (c) 2019 Luis Farzati

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

    http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.


================================================
FILE: README.md
================================================
<img src="localdots.png" height="56" />

![Docker Cloud Build Status](https://img.shields.io/docker/cloud/build/rnbw/localdots)

## localdots — HTTPS domains for localhost

Inspired by https://smallstep.com/blog/step-v0-8-6-valid-https-certificates-for-dev-pre-prod/

## Important/Disclaimer

⚠️ **This tool installs a root CA in your system. Use it only if you know what you are doing.**

### Also Important

As the title says, this tool is to be used for development. It is not meant to run at production and it hasn't been tested in CI environments either.

Please help report any issues!

## Features

localdots combines [Caddy](https://github.com/caddyserver/caddy) and [smallstep/certificates](https://github.com/smallstep/certificates) with automated configuration and hot reload.

- Generates SSL/TLS certificates automatically
- Reloads Caddy automatically with every change

## Usage

```yaml
# docker-compose.yaml

version: "3"

services:
  proxy:
    image: rnbw/localdots
    ports:
      - 80:80 # for http->https redirection
      - 443:443
    volumes:
      # contains all vhost files
      - ./caddy.d:/caddy.d:ro
      # contains CA config and certs
      - ~/.caroot:/caroot
    # only needed for *.localhost domains
    extra_hosts:
      - "whoami.localhost:127.0.0.1"

  # example containers
  whoami:
    image: jwilder/whoami
  hello:
    image: nginxdemos/hello
```

```bash
# ./caddy.d/whoami.localhost
whoami.localhost {
  proxy / whoami:8000
}

# ./caddy.d/hello.dev
hello.dev {
  proxy / hello
}
```

```bash
# run all the things
docker-compose up -d

# add the domains to your /etc/hosts file
# *.localhost domains shouldn't need to be added for typical use cases
127.0.0.1  hello.dev

# after localdots container is up and running,
# you will see a .caroot directory in your $HOME.
brew install step \
    && step certificate install ~/.caroot/certs/root_ca.crt

# that's it, try open the sites configured above
open https://whoami.localhost
open https://hello.dev
```

## About domains

### Using special TLDs

When picking a TLD for local development, you can use one of the special domain names suggested in [RFC6761](https://tools.ietf.org/html/rfc6761), such as `test` or `localhost`.

`localhost` has, [by spec](https://tools.ietf.org/html/rfc6761#section-6.3), the following particularities:

```
1.  Users are free to use localhost names as they would any other
    domain names.  Users may assume that IPv4 and IPv6 address
    queries for localhost names will always resolve to the respective
    IP loopback address.

2.  Application software MAY recognize localhost names as special, or
    MAY pass them to name resolution APIs as they would for other
    domain names.

3.  Name resolution APIs and libraries SHOULD recognize localhost
    names as special and SHOULD always return the IP loopback address
    for address queries and negative responses for all other query
    types.  Name resolution APIs SHOULD NOT send queries for
    localhost names to their configured caching DNS server(s).
```

However, if you expect `anything.localhost` to be resolved to 127.0.0.1 automatically, that might not work. For example, you can open it in Chrome and the browser will resolve it fine. But if you ping it or curl it, you'll get an error unless you add the record in your hosts file.

See https://tools.ietf.org/html/draft-west-let-localhost-be-localhost-06.

### Using any TLD

Using any of the domains above, you can be sure you won't run into any conflicts. But other than that, there's no reason why you cannot use any other "registrable" domain. There are [~1600 possible TLDs](https://www.iana.org/domains/root/db) you can choose from, or even invent your own!

While this can be seen as bad practice, I leave it to you. Personally I've seen several companies or dev teams using `xyz`, `wtf`, `lol`, `dev`, `net`, `host`, or even custom ones (i.e. not in the list) such as using the company name or team.

In my opinion, as long as you 1- know what you are doing, 2- don't shadow an existing domain that you or someone in your team uses (e.g. don't use `gmail.com`...) and 3- keep it scoped to your local development environment, then just use whatever works for you.

As with special domains, remember to add the necessary entries in your hosts file. Alternatively in this case, if you own the domain then you can always add the record in your DNS.

## Contributing
Bugfixes, improvements, proposals are gladly welcome!


================================================
FILE: caddy.d/hello.dev.example
================================================
hello.dev {
  proxy / hello
}


================================================
FILE: caddy.d/whoami.localhost
================================================
whoami.localhost {
  proxy / whoami:8000
}


================================================
FILE: docker-compose.yaml
================================================
version: "3"

services:
  proxy:
    image: rnbw/localdots
    ports:
      - 80:80 # for http->https redirection
      - 443:443
    volumes:
      # contains all vhost files
      - ./caddy.d:/caddy.d:ro
      # contains CA config and certs
      - ~/.caroot:/caroot

  # example containers
  whoami:
    image: jwilder/whoami
  hello:
    image: nginxdemos/hello


================================================
FILE: start.sh
================================================
#!/bin/sh

reload_caddy() {
  if [ -f $CADDY_PIDFILE ]; then
    kill -SIGUSR1 $(cat $CADDY_PIDFILE)
  else
    PROVISIONER=$(cat $STEPPATH/config/ca.json | jq -r ".authority.provisioners[0].name")
    LEGO_CA_CERTIFICATES=$STEPPATH/certs/root_ca.crt /usr/bin/caddy \
      --conf $CADDYFILE \
      --log stdout \
      -ca https://localhost:8443/acme/acme/directory \
      -email $PROVISIONER \
      -disable-tls-alpn-challenge \
      -pidfile $CADDY_PIDFILE &
  fi
}

# First-time CA configuration
if [ ! -f $STEPPATH/config/ca.json ]; then
  echo "$STEPPATH/config/ca.json not found; creating new CA"

  PROVISIONER=$(cat /dev/urandom | tr -dc 'a-zA-Z0-9' | fold -w 8 | head -n 1)@localdots.example
  PASSWORD=$(cat /dev/urandom | tr -dc 'a-zA-Z0-9' | fold -w 32 | head -n 1) \
    && echo $PASSWORD > /tmp/password \
    && step ca init \
      --name=localdots \
      --dns=localhost \
      --address=127.0.0.1:8443 \
      --provisioner=$PROVISIONER \
      --password-file=/tmp/password \
    && mv /tmp/password $STEPPATH/secrets/password \
    && step ca provisioner add acme --type ACME
fi

# Starts ACME server and Caddy
step-ca --password-file $STEPPATH/secrets/password $STEPPATH/config/ca.json &
sleep 1
rm -f $CADDY_PIDFILE
reload_caddy

# Caddy configuration watcher
inotifywait -e "create,delete,modify,move" --monitor $CADDY_D --monitor $CADDYFILE | \
  while read -r notifies;
  do
    echo
    echo "$notifies"
    reload_caddy
  done