|
| 1 | +# Pico Stack: Core Services |
| 2 | + |
| 3 | +This repository contains the core services that form the foundation of the Pico Stack. It contains: |
| 4 | + |
| 5 | +- [Traefik][traefik]: as a HTTP gateway and for automatic SSL certificates |
| 6 | +- [Portainer][portainer]: to see what's running |
| 7 | +- [Watchtower][watchtower]: for keeping container images up to date |
| 8 | +- [Grafana][grafana]: for viewing logs, metrics and alerts |
| 9 | +- [Prometheus][prometheus]: for metric collection |
| 10 | +- [Node Exporter][node_exporter]: for system metrics |
| 11 | +- [cAdvisor][cadvisor]: for container metrics |
| 12 | +- [Loki][loki]: for log aggregation |
| 13 | + |
| 14 | +This project is designed to be plug-and-play and kept up to date. It's perfect for small to medium deployments in individual servers where Kubernetes is considered overkill. |
| 15 | + |
| 16 | +I ([Southclaws][southclaws]) run this exact stack on my production servers using [Pico][pico] to always use the latest commit. So it should be always up to date and in a working state. If you find a problem with the setup or documentation, please open an issue. |
| 17 | + |
| 18 | +## Deployment |
| 19 | + |
| 20 | +Deployment is quite simple the first time around. Provided your execution environment ([Pico][pico] or a shell) has the necessary environment variables, it's just a `docker-compose up -d` followed by some logging and first-time configuring. |
| 21 | + |
| 22 | +All you need is: |
| 23 | + |
| 24 | +- A server, virtual or physical |
| 25 | +- A domain name |
| 26 | + |
| 27 | +### Environment Variables |
| 28 | + |
| 29 | +```sh |
| 30 | +HOSTNAME=server001 |
| 31 | +DATA_DIR=/data/shared |
| 32 | +DOMAIN_NAME=myawesomeproject.com |
| 33 | +ACME_EMAIL=admin@myawesomeproject.com |
| 34 | +CA_SERVER=https://acme-v02.api.letsencrypt.org/directory |
| 35 | +CORE_SERVICES_BASIC_AUTH=2ドルa1ドル14ドル/ET4dmxtvpW1mgvc9F8qus.gNb9MMFxOxfRGLDA02wACCIIfCYnC |
| 36 | +``` |
| 37 | + |
| 38 | +#### `HOSTNAME` |
| 39 | + |
| 40 | +The name of the machine. This is required used for building domains for services. |
| 41 | + |
| 42 | +#### `DATA_DIR` |
| 43 | + |
| 44 | +This is where data will be persisted on the host machine. |
| 45 | + |
| 46 | +- `${DATA_DIR}/traefik/acme`: Traefik ACME storage |
| 47 | +- `${DATA_DIR}/portainer_data`: Portainer user data |
| 48 | +- `${DATA_DIR}/prometheus`: Prometheus database |
| 49 | +- `${DATA_DIR}/grafana`: Grafana user data |
| 50 | +- `${DATA_DIR}/loki`: Log storage |
| 51 | + |
| 52 | +`/data/shared` is a commonly used value for this variable. |
| 53 | + |
| 54 | +#### `DOMAIN_NAME` |
| 55 | + |
| 56 | +A domain name you own. See the Domains section below for details. |
| 57 | + |
| 58 | +#### `ACME_EMAIL` |
| 59 | + |
| 60 | +Your email address for registering SSL certificates with LetsEncrypt. |
| 61 | + |
| 62 | +#### `CA_SERVER` |
| 63 | + |
| 64 | +The value of `CA_SERVER` depends if you're deploying for the first time. Because LetsEncrypt has some pretty harsh rate limiting rules and you get banned for a whole week if you hit the limit, you should deploy using the staging server first to make sure your domains are all working correctly. Then, once you're happy with the setup, switch to the live server. |
| 65 | + |
| 66 | +Staging: |
| 67 | + |
| 68 | +``` |
| 69 | +CA_SERVER=https://acme-staging-v02.api.letsencrypt.org/directory |
| 70 | +``` |
| 71 | + |
| 72 | +Live: |
| 73 | + |
| 74 | +``` |
| 75 | +CA_SERVER=https://acme-v02.api.letsencrypt.org/directory |
| 76 | +``` |
| 77 | + |
| 78 | +#### `BASIC_AUTH` |
| 79 | + |
| 80 | +A HTTP basic auth string to use as a login for all the running services with a web interface. |
| 81 | + |
| 82 | +## Domains |
| 83 | + |
| 84 | +The compose configuration uses the convention `service-hostname.domain`. So, lets assume you own `myawesomeproject.com` and your machine is called `felix`. Your services would run on: |
| 85 | + |
| 86 | +- `traefik-felix.myawesomeproject.com` |
| 87 | +- `portainer-felix.myawesomeproject.com` |
| 88 | +- `cadvisor-felix.myawesomeproject.com` |
| 89 | +- `prometheus-felix.myawesomeproject.com` |
| 90 | +- `grafana-felix.myawesomeproject.com` |
| 91 | + |
| 92 | +## Auth |
| 93 | + |
| 94 | +Both Grafana and Portainer have built-in user systems. The rest will use the `BASIC_AUTH` to set a basic HTTP login via Traefik. |
| 95 | + |
| 96 | +When you first open Grafana, log in with `admin`/`admin` then change the password. |
| 97 | + |
| 98 | +When you first open Portainer, create an admin account and connect it to the local Docker socket (the option on the far right). |
| 99 | + |
| 100 | +The rest will just prompt a login dialog on your browser. |
| 101 | + |
| 102 | +[traefik]: https://traefik.io |
| 103 | +[portainer]: https://portainer.io |
| 104 | +[watchtower]: https://containrrr.github.io/watchtower/ |
| 105 | +[grafana]: https://grafana.com |
| 106 | +[prometheus]: https://prometheus.io |
| 107 | +[node_exporter]: https://github.com/prometheus/node_exporter |
| 108 | +[cadvisor]: https://github.com/google/cadvisor |
| 109 | +[loki]: https://github.com/grafana/loki/ |
| 110 | +[southclaws]: https://southcla.ws |
| 111 | +[pico]: https://github.com/picostack/pico |
0 commit comments