From 784aee93970c31e09ca3a5196b049ef8d9a0a00d Mon Sep 17 00:00:00 2001 From: Michael Housh Date: Thu, 20 Mar 2025 10:58:40 -0400 Subject: [PATCH] feat: Updates readme to be more descriptive. --- README.md | 30 ++++++++++++++++++++++++++++++ 1 file changed, 30 insertions(+) diff --git a/README.md b/README.md index d8aad0d..2fd956d 100644 --- a/README.md +++ b/README.md @@ -2,4 +2,34 @@ This organizes files and configuration for services that run on our network servers. +## Overview + +The image below is a high level overview of the network configuration. There may be more servers +added to run services in the future, however the primary point is that there is a `primary` server +that acts as the entry point to all the services that are running. This server also may run services +as well, but is beyond the scope of the overview. + ![network](img/housh.dev.network.svg) + +The `primary` server runs an instance of [caddy](https://caddyserver.com/docs/) that is used as a +reverse proxy to the internal services. It manages SSL certificates and routes traffic to the +appropriate server where the service is running. This allows for the service to be moved between +different backend servers, but accessed via the same URL. + +The services are only available on our internal network, so to access them one needs to be connected +to our network directly or through a VPN. + +## DNS + +DNS is what translates human readable URL's, such as `po.housh.dev`, and translates it to an IP +address (i.e. 192.168.50.5). The DNS is handled by our unifi router which just points any domain +that ends in `housh.dev` to the `primary` server which can then route the traffic appropriately. + +The unifi router does also have DNS records for each backend servier that works in a similar +fashion, this is primarily an implementation detail that doesn't really matter, however it allows +routes declared on the `primary` caddy server to route traffic based on the server domain name (i.e. +frankenmini.housh.dev) vs. needing the internal IP address of the server. + +This setup allows a fairly easy transition if the `primary` server that runs caddy is changed in the +future, then only the DNS record for `*.housh.dev` only needs to be updated on the unifi router to +properly route traffic to the correct `primary` server.