From ab0c5c12092b0d821a32bef656bbcb4fe3fcef22 Mon Sep 17 00:00:00 2001 From: April Petersen Date: Mon, 6 Jan 2025 09:40:27 -0600 Subject: [PATCH] add smtp info and syntax highlighting --- readme.md | 85 +++++++++++++++++++++++++++++++++++++++---------------- 1 file changed, 61 insertions(+), 24 deletions(-) diff --git a/readme.md b/readme.md index 4b53158..e13be99 100644 --- a/readme.md +++ b/readme.md @@ -54,7 +54,7 @@ These are all the services hosted here, what they are for, and any clients I use ### Networking - [cloudflared](https://github.com/cloudflare/cloudflared) - CloudFlare tunnel client for easy and secure external service access -- [gluetun](https://github.com/qdm12/gluetun) - Docker VPN client +- [gluetun](https://github.com/qdm12/gluetun) - Docker VPN client and kill-switch. Very useful, allows for per-container VPN connectivity. - [AdGuard Home](https://adguard.com/en/adguard-home/overview.html) - DNS filtering - I use this with [tailscale](https://tailscale.com/) to block ads on my phone Note that I run tailscale on bare metal so it is not listed here, but it is very useful for remote access to services I don't want visible on the open internet as well as SSH access. @@ -69,11 +69,30 @@ Note that I run tailscale on bare metal so it is not listed here, but it is very I use [LunaSea](https://www.lunasea.app/) as a mobile client for Radarr and Sonarr. -## Environment - This configuration uses `.env` files to separate secrets from public information and maintain brevity in the main `docker-compose.yml` -Here are the variables that need to be set in the `.env` file for each service. Empty variables should be replaced with your values. +## Environment + +Below are the variables that need to be set in the `.env` file for each service. Empty variables should be replaced with your values. + +> **A Note on Email** +> +> Several of these env files include SMTP settings, which are completely optional. Automated email sending is very useful for user signups, 2FA, account recovery, and notifications, but email is notoriously difficult to self-host. The solution I've found works very well and generally gets past spam filters. +> +> I use [SendGrid](https://sendgrid.com/en-us) with CloudFlare's [email routing](https://blog.cloudflare.com/introducing-email-routing/) for email. I have a catch-all rule in CloudFlare that forwards all emails to a dedicated Gmail address, and that address uses a `Send Mail As` address set up with SendGrid's SMTP for sending emails by hand. +> +> By default, emails sent this way will show a little `via sendgrid.net` notice. To remove this, [verify your domain](https://www.twilio.com/docs/sendgrid/ui/account-and-settings/how-to-set-up-domain-authentication) with SendGrid. +> +> Also, link tracking is enabled by default and should be disabled in SendGrid's tracking settings. +> +> **SMTP Settings:** +> +> - Host: `smtp.sendgrid.net` +> - Port: `587` +> - Security: `tls` (or equivalent, e.g. `starttls` for vaultwarden) +> - Username: `apikey` +> - Password: API Key generated in SendGrid +> - From: `@` - For each custom sender (`mailer-name`), there needs to be a verified sender in SendGrid. ### cloudflared @@ -81,9 +100,9 @@ Here are the variables that need to be set in the `.env` file for each service. ### gluetun -The values below are specific to Mullvad VPN. Other providers need different values, refer to gluetun documentation. +The values below are specific to Mullvad VPN ([docs](https://github.com/qdm12/gluetun-wiki/blob/main/setup/providers/mullvad.md)). Other providers need different values, refer to the corresponding gluetun documentation. -``` +```env VPN_SERVICE_PROVIDER=mullvad VPN_TYPE=wireguard WIREGUARD_PRIVATE_KEY= @@ -91,15 +110,15 @@ WIREGUARD_ADDRESSESS= SERVER_CITIES= ``` -The actual values should be available in the WireGuard configuration from Mullvad. +The values for `WIREGUARD_PRIVATE_KEY` and `WIREGUARD_ADDRESSES` should be available in the WireGuard configuration file generated by Mullvad. `SERVER_CITIES` should be set to the city of your configuration's selected exit node. ### Immich -My current Immich docker setup includes a lot of repetition - when I want to update, I have to change the version in 3 places. +My current Immich docker setup includes a lot of repetition - when I want to update, I have to change the version in 3 places. I have plans to improve this, but for now this is what works. Also note that the way I set the upload location is not recommended by the Immich docs. -I have plans to improve this, but for now this is what works. +For more information, see the Immich [docker-compose setup instructions](https://immich.app/docs/install/docker-compose/). -``` +```env UPLOAD_LOCATION=/media/immich IMMICH_VERSION="v1.123.0" @@ -120,7 +139,9 @@ POSTGRES_DB=immich ### Joplin -``` +See the [docker-joplin-server docs](https://github.com/flosoft/docker-joplin-server) for more info. + +```env APP_PORT=22300 APP_BASE_URL= DB_CLIENT=pg @@ -130,7 +151,7 @@ POSTGRES_USER= POSTGRES_PORT=5432 POSTGRES_HOST=joplin-db -# Optional SMTP email options +# Optional SMTP options MAILER_ENABLED=1 MAILER_HOST= MAILER_PORT=465 @@ -143,14 +164,18 @@ MAILER_NOREPLY_EMAIL= ### LinkStack -``` +This one just needs the public hostname and admin email. [Docs](https://linkstack.org/docker/). + +```env HTTPS_SERVER_NAME= SERVER_ADMIN= ``` ### Miniflux -``` +[Docs](https://miniflux.app/docs/docker.html) + +```env DATABASE_URL=postgres://miniflux:{...}@rss_db:5432/miniflux?sslmode=disable # replace {...} with your postgres password RUN_MIGRATIONS=1 @@ -161,7 +186,9 @@ POSTGRES_DB=miniflux ### Paperless-ngx -``` +[Docs](https://docs.paperless-ngx.com/setup/#docker) + +```env USERMAP_UID=1000 USERMAP_GID=1000 PUID=1000 @@ -169,7 +196,7 @@ PGID=1000 PAPERLESS_URL= -# random secret key, use for example `base64 /dev/urandom | head -c50` to generate one +# Random secret key, use for example `base64 /dev/urandom | head -c50` to generate one PAPERLESS_SECRET_KEY= PAPERLESS_TIME_ZONE= @@ -190,7 +217,9 @@ PAPERLESS_EMAIL_FROM= ### Speedtest Tracker -``` +[Docs](https://docs.speedtest-tracker.dev/getting-started/installation/using-docker-compose). `APP_URL` is the public address, `APP_KEY` is generated with `echo -n 'base64:'; openssl rand -base64 32;` + +```env PUID=1000 PGID=1000 APP_KEY= @@ -203,14 +232,16 @@ SPEEDTEST_SCHEDULE=0,15,30,45 * * * * # run speedtest every 15 minutes ### Tandoor -``` -# random secret key, use for example `base64 /dev/urandom | head -c50` to generate one +[Docs](https://docs.tandoor.dev/install/docker/). + +```env +# Random secret key, use for example `base64 /dev/urandom | head -c50` to generate one SECRET_KEY= -# allowed hosts (see documentation), should be set to your hostname(s) but might be * (default) for some proxies/providers +# Allowed hosts (see documentation), should be set to your hostname(s) but might be * (default) for some proxies/providers ALLOWED_HOSTS= -# add only a database password if you want to run with the default postgres, otherwise change settings accordingly +# Add only a database password if you want to run with the default postgres, otherwise change settings accordingly DB_ENGINE=django.db.backends.postgresql POSTGRES_HOST=tandoor-db POSTGRES_DB=tandoor @@ -221,13 +252,19 @@ POSTGRES_PASSWORD= ### vaultwarden -``` +[Docs](https://github.com/dani-garcia/vaultwarden). Note that the crypto API requires HTTPS, so local access is a bit of a challenge. + +These values are only required if you need to use the vaultwarden admin page (for user management, SMTP, hardware 2FA, etc.). The `ADMIN_TOKEN` value gave me trouble - to make it work, I used the 'Using `argon2`' instructions from [Enabling admin page](https://github.com/dani-garcia/vaultwarden/wiki/Enabling-admin-page) in the docs. At `your-ip-or-url.com/admin`, the password you used for the hash will unlock it (e.g. `MySecretPassword` per their example). + +Note: The `ADMIN_TOKEN` value should be enclosed in single quotes. If it is not, all instances of `$` in the value will need to be replaced with `$$` to prevent the value from being split by the parser. + +```env DOMAIN= -# dollar signs must be replaced with two dollar signs to properly escape variables in this token +# Dollar signs must be replaced with two dollar signs to properly escape variables in this token ADMIN_TOKEN= -# optional SMTP email settings +# Optional SMTP email settings SMTP_HOST= SMTP_FROM= SMTP_PORT=587