diff --git a/README.md b/README.md index e63eae7..0051456 100644 --- a/README.md +++ b/README.md @@ -16,7 +16,7 @@

- UltimateHomeServer.com (coming soon) + UltimateHomeServer.com

@@ -26,7 +26,7 @@ ## Getting Started -View the [docs](docs/README.md) for a detailed guide on how to get started. +View the [docs](https://www.ultimatehomeserver.com/docs/) for a detailed guide on how to get started. --- @@ -62,6 +62,12 @@ View the [docs](docs/README.md) for a detailed guide on how to get started. --- +## CLI + +View the [`uhs-cli` repository](https://github.com/TechSquidTV/uhs-cli) for more information. + +--- + ## Thanks

Made with ❤️, built on the backs of *arr stack, linuxserver.io, and more awesome open-source projects. diff --git a/docs/Customize.md b/docs/Customize.md deleted file mode 100644 index 2ba3915..0000000 --- a/docs/Customize.md +++ /dev/null @@ -1,172 +0,0 @@ -# Customize services - -Before deploying your home services, you will need to customize the configuration to your liking and create some local directories to store the configuration for each service. - -## Enable and customize - -In the `values.yaml` file you will find the _default_ configuration for each service with example values. This file should typically _not_ be modified. Instead, you will customize the `secrets.yaml` file with the values you want to override. - -### Create `secrets.yaml` - -It is recommended you reference the existing `secrets.yaml` file, but you may want to rename it to something like `secrets.example.yaml` and create your own new `secrets.yaml` file. - -```bash -cp secrets.yaml secrets.example.yaml -``` -```bash -touch secrets.yaml -``` -``` -echo "secrets.example.yaml" >> .gitignore -``` - -Ensure your secrets.yaml file retains the `common` section, which contains the timezone and SSL certificate configuration: - -```yaml -common: - tz: America/New_York - certs: - ssl_certificate: ${HELM_SSL_CERT} - ssl_certificate_key: ${HELM_SSL_KEY} - ssl_dhparam: ${HELM_SSL_DHPARAM} -``` - -You may include your secret values directly in the `secerts.yaml` file only if you remove and exclude the file from git tracking. Otherwise, you can store your secret values in a `.env` file and reference them in the `secrets.yaml` file. - -### Create `.env` - -Copy the `.env.example` file to `.env` - -```bash -cp .env.example .env -``` - -Not all values must be filled, and some are only there as a convenience. You may fill in only what you reference in `secrets.yaml`. - -Add the secrets referenced in the `common` section of `secrets.yaml` to your `.env` file: - -```bash -TZ=America/New_York - -HELM_SSL_CERT=/etc/letsencrypt/live//fullchain.pem -HELM_SSL_KEY=/etc/letsencrypt/live//privkey.pem -HELM_SSL_DHPARAM=/etc/letsencrypt/certs/dhparam.pem - -``` - -### Enabling a service - -Here is an example workflow for enabling a service. We will use the `plex` service as an example. - -In `values.yaml`, you will see under _`services.plex`_ all of the default configuration for the service, such as the image, ports, and environment variables. - -Notice each service has an `enabled` key set to false by default. To enable a service we will set this to true in `secrets.yaml`. - -Here is an example of what `secrets.yaml` might look like after enabling the `plex` service: - -```yaml -common: - tz: America/New_York - certs: - ssl_certificate: ${HELM_SSL_CERT} - ssl_certificate_key: ${HELM_SSL_KEY} - ssl_dhparam: ${HELM_SSL_DHPARAM} - -services: - plex: - enabled: true - library: - tv: ${PLEX_LIB_TV} - movies: ${PLEX_LIB_MOVIES} - config: ${PLEX_CONFIG} -``` -Here would be the corresponding `.env` file: - -```bash -TZ=America/New_York - -HELM_SSL_CERT=/etc/letsencrypt/live//fullchain.pem -HELM_SSL_KEY=/etc/letsencrypt/live//privkey.pem -HELM_SSL_DHPARAM=/etc/letsencrypt/certs/dhparam.pem - - -PLEX_LIB_TV=/z-pool/plex/library/tv -PLEX_LIB_MOVIES=/z-pool/plex/library/movies -PLEX_CONFIG=/z-pool/plex/config -``` - -#### Ensure all directories exist - -When you enable a service, you will need to ensure all of the directories referenced in the `secrets.yaml` file exist. If they do not, you will need to create them. - -```bash -mkdir -p /z-pool/plex/library/tv -mkdir -p /z-pool/plex/library/movies -mkdir -p /z-pool/plex/config -``` - -Make sure the created directories are writable. - -```bash -chmod -R 660 /z-pool/plex -``` - -### Validate Helm template - -After customizing your configuration, it is a good idea to validate the Helm template for mistakes - -## Homepage Dashboard - -Enable the [`homepage`](https://gethomepage.dev/en/installation/) service to get a dashboard of all your services and bookmarks at `https://homepage./`. - -Homepage can be customized by editing the _services_, _bookmarks_, _widgets_, and _settings_ configurations. These would typically be separate YAML files, but for simplicity, they are all included in the `secrets.yaml` file under the `homepage` section. - -```yaml -services: - homepage: - enabled: true - services: - - My First Group: - - My First Service: - href: http://localhost/ - description: Homepage is awesome - bookmarks: - - Developer: - - Github: - - abbr: GH - href: https://github.com/ - widgets: - - kubernetes: - cluster: - show: true - cpu: true - memory: true - showLabel: true - label: "cluster" - nodes: - show: true - cpu: true - memory: true - showLabel: true - - resources: - backend: resources - expanded: true - cpu: true - memory: true - - search: - provider: google - target: _blank -``` - -View the official [Homepage documentation](https://gethomepage.dev/en/configs/services/) for more information on how to customize the dashboard. - -## *Arr Services - -Many of the services available in this chart are part of the [*Arr](https://wiki.servarr.com/) stack, a collection of services built from the same codebase and designed to work together to "grab", sort, and monitor media files. - -You can read all about the *Arr services on the [Servarr Wiki](https://wiki.servarr.com/). - -# See Also - -- [Docs](./README.md) -- [Deploy](./Deploy.md) \ No newline at end of file diff --git a/docs/README.md b/docs/README.md deleted file mode 100644 index 50ac7dd..0000000 --- a/docs/README.md +++ /dev/null @@ -1,111 +0,0 @@ -# Getting Started - -Configure the ultimate home server with [K3s](https://k3s.io/) and [Helm](https://helm.sh/). - -## Prerequisites - -- Ubuntu 20.04 (or newer) server -- A domain name -- Basic knowledge of Linux commands - -### Recommended Hardware (_to run all services_) -- **CPU**: 8+ cores -- **RAM**: 32+ GB - -Running only a few services should work on a Raspberry Pi 4 with 4 GB of RAM. - -## Setup your server - -In a freshly installed Ubuntu 20.04 (or newer) server, begin by ensuring your system is up to date: - -```bash -sudo apt update && sudo apt upgrade -y -``` - -Install some useful tools: - -```bash -sudo apt install -y curl git gettext-base nano -``` - -### RAID storage - -If you plan on configuring a RAID array for your storage, you may want to do this now. We recommend using ZFS to create a RAIDZ1 array with at least 3 disks. See [this guide](https://ubuntu.com/tutorials/setup-zfs-storage-pool#1-overview). - -### Install K3s - -[k3s](https://k3s.io/) is a lightweight Kubernetes distribution. It's a great choice for our home server because it has a small resource footprint, supports single-node clusters, and supports mounting a local path as a persistent volume. - -```bash -curl -sfL https://get.k3s.io | sh - -``` - -### Install Helm - -[Helm](https://helm.sh/) is a package manager for Kubernetes. It allows us to easily install and manage applications on our cluster. - -```bash -curl -fsSL -o get_helm.sh https://raw.githubusercontent.com/helm/helm/main/scripts/get-helm-3 -``` - -```bash -chmod 700 get_helm.sh -``` - -```bash -./get_helm.sh -``` - -### Clone this repository - -```bash -git clone https://github.com/TechSquidTV/UltimateHomeServer /opt/homeserver -``` - -## Configure a domain name - -We will use a domain to access our server locally with a valid SSL certificate. - -Before we begin, we will need to know the local IP address of our server. We can find this by running: - -```bash -ip addr -``` - -You should configure your router to assign a static IP address to your server if you have not already. - -1. Once you have your server's IP address, you can configure a domain name. You can obtain a domain name from a registrar of your choice. -2. In the DNS settings for your domain, create an `A` record that points to your server's IP address. -3. Create a second `A` record that points to your server's IP address, but with a subdomain of `*.`, this will be used for wildcard subdomains. - -[![DNS Settings](../.github/img/dns_records.png)](../.github/img/dns_records.png) - -## Configure SSL - -Read the [SSL](SSL.md) guide for instructions on how to configure SSL for your domain using certbot. This step is _required_. - -## Customize services - -Read the [Customize](Customize.md) guide for instructions on how to customize the services you want to deploy. - -## Deploy services - -Once you have configured your server, domain with ssl, and customized the services you want to deploy, you can create the helm deployment. - -To make it easier to load your environment variables from the `.env` file, the deployment and update commands have been wrapped in scripts. You can run the deployment script with: - -```bash -./bin/deploy.sh -``` - -## Verify services - -Read the [Troubleshooting](Troubleshooting.md) guide for instructions on how to verify that the services are running correctly. - -## Update services - -To update the services, you can run the update script with: - -```bash -./bin/upgrade.sh -``` diff --git a/docs/SSL.md b/docs/SSL.md deleted file mode 100644 index 6e05e9e..0000000 --- a/docs/SSL.md +++ /dev/null @@ -1,72 +0,0 @@ -# Configure SSL - -Rather than configuring ingress in our cluster, we opt to use a simpler approach suitable for our home-server using [certbot](https://certbot.eff.org/) to create a wildcard cert and [nginx](https://www.nginx.com/) as our reverse proxy. We can then mount the certificates as a volume in our cluster. - -### Install certbot - -In this tutorial we will opt for a more manual approach to installing certbot, to avoid running the snap daemon. - -Follow the official guide on [certbot.eff.org](https://certbot.eff.org/instructions?ws=other&os=pip) to install certbot with pip. - -Once certbot is installed and available at `/usr/local/bin/certbot`, we can create a certificate for our domain. - -Certbot supports automatic DNS validation with many DNS providers. Install the plugin for your provider. See the list of available [DNS plugins here.](https://eff-certbot.readthedocs.io/en/stable/using.html#dns-plugins) - -In this example, we will use Cloudflare as our DNS provider. To install the Cloudflare plugin, run: - -```bash -sudo /opt/certbot/bin/pip install certbot-dns-cloudflare -``` - -### Configure DNS credentials - -The documentation above listing the DNS plugins will also provide instructions on how to configure credentials for your DNS provider. - -If you are using Cloudflare, continue with the following steps. - -1. Create a [Cloudflare API token](https://developers.cloudflare.com/fundamentals/api/get-started/create-token/) with the following permissions: - - `Zone:Zone:Read` - - `Zone:DNS:Edit` -2. Create a directory to store your credentials. A common practice is to create a directory in your home directory called `.secrets`. - ```bash - mkdir -p ~/.secrets/certbot - ``` -3. Create a file in this directory called `cloudflare.ini` with the following contents: - ```ini - # Cloudflare API token used by Certbot - dns_cloudflare_api_token = - ``` -4. Set the permissions on this file to `600`: - ```bash - chmod 600 ~/.secrets/certbot/cloudflare.ini - ``` -5. Run the following command to create a wildcard certificate for your domain: - ```bash - sudo /opt/certbot/bin/certbot certonly \ - --dns-cloudflare \ - --dns-cloudflare-credentials ~/.secrets/certbot/cloudflare.ini \ - --dns-cloudflare-propagation-seconds 60 \ - -d - -d *. - ``` - Certbot will create a certificate and store it in `/etc/letsencrypt/live/`. We will use this certificate in our cluster. -6. Setup automatic renewal by running the `certbot renew` command in a cron job. Run the following command: - ```bash - echo "0 0,12 * * * root /opt/certbot/bin/python -c 'import random; import time; time.sleep(random.random() * 3600)' && sudo certbot renew -q" | sudo tee -a /etc/crontab > /dev/null - ``` - Certbot will check the expiration date of your certificate twice a day and renew it if it is within 30 days of expiration. -7. Test the renewal process by running: - ```bash - sudo /opt/certbot/bin/certbot renew --dry-run - ``` - If the command runs without errors, the renewal process is working correctly. -8. Lastly, create a Diffie-Hellman parameters certificate for additional security: - ```bash - sudo openssl dhparam -out /etc/letsencrypt/certs/dhparam.pem 2048 - ``` - For convenience we will store this certificate in the same directory as our letsencrypt certificates. - -# See Also - -- [Docs](./README.md) -- [Customize](./Customize.md) diff --git a/docs/Troubleshooting.md b/docs/Troubleshooting.md deleted file mode 100644 index 1149224..0000000 --- a/docs/Troubleshooting.md +++ /dev/null @@ -1,29 +0,0 @@ -# Troubleshooting - -## Verify services - -Once the deployment or upgrade is complete, there are a number of ways to verify that the services are running correctly. - -### Verify the Helm deployment - -List the current helm deployments and verify that the `` deployment is listed. - -```bash -helm ls -``` - -### Verify the Kubernetes pods - -List the current pods and verify that all pods are in the `Running` state. - -```bash -kubectl get pods -A -``` - -## View logs - -To view the logs for a specific service, you can use the `kubectl logs` command. - -```bash -kubectl logs -``` \ No newline at end of file