|
3 | 3 |
|
4 | 4 | Minithor utilizes Minikube to provide a local Kubernetes instance with minimal custom configuration required. Such an instance is useful for development and testing of Thorium as well as small stand alone analyst fly-away kits where external network access may not be available. Minithor deployments are not highly available distributed systems like our production instances and provides minimal redundancy. The Thorium deployment produced by following these instructions should be considered Beta. We will work to improve its stability over time. While a Minithor deployment is accessible only from your localhost, it has not been configured to be secure. Please change DB passwords if working with sensitive data on a multi-user system using a Minithor deployment. |
5 | 5 |
|
6 | | -### Requirements and "Disclosures" |
| 6 | +### Requirements |
7 | 7 |
|
8 | | -To deploy Minithor, you will need a container runtime such as that provided by the docker engine. Minithor also requires a relatively beefy machine, with > 12 GiB of memory, 8+ CPUs, and 100GiB of local storage. You will also need to install s3cmd if it is not already installed on the host system, this enables deployment of a s3 bucket for storing traces pushed to Quickwit. |
| 8 | +To deploy Minithor, you will need a container runtime such as that provided by the docker engine or podman. Minithor also requires a relatively beefy machine, with > 12 GiB of memory, 8+ CPUs, and 100GiB of local storage. |
9 | 9 |
|
10 | | -On a Mac using brew: |
11 | | - |
12 | | -```bash |
13 | | -brew install s3cmd |
14 | | -``` |
15 | | - |
16 | | -On Linux: |
17 | | - |
18 | | -```bash |
19 | | -apt install s3cmd |
20 | | -``` |
21 | | - |
22 | | -### Deploy Minikube |
| 10 | +### Install Minikube |
23 | 11 |
|
24 | 12 | Install and start minikube and any necessary plugins. |
25 | 13 |
|
26 | 14 | ```bash |
27 | | -./install-linux |
28 | | -# or ./install-mac-m1 |
| 15 | +./install |
29 | 16 | ``` |
30 | 17 |
|
31 | | -Add this to your environment settings after installation: |
32 | | - |
33 | | -```bash |
34 | | -alias kubectl="minikube kubectl --" |
35 | | -``` |
| 18 | +### Create registry auth file (optional) |
36 | 19 |
|
37 | | -### Create registry auth file |
38 | | - |
39 | | -In the project directory you will need to create a file called `.dockerconfigjson` containing the authentication credentials for the user account/registry containing the thorium container image. |
40 | | - |
41 | | -Create the `.dockerconfigjson` via the `docker login` command. The registry url must match that used by the images Thorium will run: |
| 20 | +If the Thorium container image is hosted in a private registry, create a `.dockerconfigjson` file in this directory containing the registry credentials. The deploy script will detect this file and create a Kubernetes image pull secret automatically. |
42 | 21 |
|
43 | 22 | ```bash |
44 | 23 | docker login registry.domain:port |
| 24 | +cp ~/.docker/config.json .dockerconfigjson |
45 | 25 | ``` |
46 | 26 |
|
47 | | -The registry auth information will be structured like this: |
| 27 | +If omitted, the operator will pull images without authentication (works for public registries like `ghcr.io`). |
48 | 28 |
|
49 | | -```bash |
50 | | -cat .dockerconfigjson |
51 | | -{ |
52 | | - "auths": { |
53 | | - "registry.domain:port": { |
54 | | - "auth": "<base64 of username:token/password>" |
55 | | - } |
56 | | - } |
57 | | -} |
58 | | -``` |
59 | | - |
60 | | -Once this registry auth file has been created, copy the file (default path is `~/.docker/config.json` for most linux systems, must be manually created on mac) to the project directory and rename it to `.dockerconfigjson`. |
| 29 | +### Proxy configuration (optional) |
61 | 30 |
|
62 | | -### Deploy Dependencies |
| 31 | +If your organization maintains a proxy for all traffic going to the internet, export proxy settings before running the deploy script: |
63 | 32 |
|
64 | | -Thorium requires persistent storage interfaces a tracing API and an operator. Lets deploy these dependencies. |
65 | | - |
66 | | -If your organization maintains a proxy for all traffic going to the internet, you will need to export proxy settings such as the following: |
67 | 33 | ```bash |
68 | | -cat proxy |
69 | | - |
70 | | -#!/bin/bash |
71 | 34 | export HTTP_PROXY=<HTTP_PROXY_URL:PORT> |
72 | 35 | export HTTPS_PROXY=<HTTPS_PROXY_URL:PORT> |
73 | 36 | export NO_PROXY=localhost,127.0.0.1,10.0.0.0/8,192.168.0.0/16 |
74 | 37 | ``` |
75 | 38 |
|
76 | | -Once you have built that proxy file it can be reused in different terminal windows with: |
77 | | - |
78 | | -```bash |
79 | | -source proxy |
80 | | -``` |
| 39 | +Or use the provided proxy file: `source proxy` |
81 | 40 |
|
82 | | -Alternatively, those proxy settings can be added into your shell's settings file. |
| 41 | +### Deploy |
83 | 42 |
|
84 | | -Now deploy the dependencies: |
| 43 | +The `deploy` script handles the full deployment in a single step: all backing services (Redis, Elasticsearch, ScyllaDB, MinIO, Quickwit, Jaeger), the Thorium operator, the ThoriumCluster resource, and a default test user. |
85 | 44 |
|
86 | 45 | ```bash |
87 | 46 | ./deploy |
88 | 47 | ``` |
89 | 48 |
|
90 | | -### Deploy Thorium |
| 49 | +This will: |
91 | 50 |
|
92 | | -```bash |
93 | | -kubectl create -n thorium -f thorium-cluster.yml |
94 | | -``` |
95 | | - |
96 | | -### Set Password For Node's Docker User |
| 51 | +1. Wait for the minikube cluster to be healthy |
| 52 | +2. Install Helm and add required chart repos |
| 53 | +3. Deploy Redis, Elasticsearch (ECK), cert-manager, ScyllaDB, MinIO, Jaeger, Kubegres, and Quickwit |
| 54 | +4. Configure databases (Scylla roles/keyspace, Elasticsearch index/user, MinIO buckets) |
| 55 | +5. Deploy the Thorium operator and create the ThoriumCluster CRD |
| 56 | +6. Wait for all Thorium components (API, scaler, event-handler, search-streamer) to be running |
| 57 | +7. Create a test admin user (`test` / `INSECURE_DEV_PASSWORD`) |
| 58 | +8. Install `thorctl` from the API and import the default toolbox (analysis tools and pipelines) |
97 | 59 |
|
98 | | -You only have to do this once and only when using priveleged ports for your local host port mapping. Kkeep track of the docker-in-docker password you set so you can tunnel to the Thorium UI/API later. |
| 60 | +To customize the ThoriumCluster configuration, copy the example and edit it before running the deploy script: |
99 | 61 |
|
100 | 62 | ```bash |
101 | | -minikube ssh |
102 | | -sudo su - |
103 | | -passwd docker |
104 | | -# New password: |
105 | | -# Retype new password: |
106 | | -# passwd: password updated successfully |
107 | | -exit |
108 | | -exit |
| 63 | +cp thorium-cluster.yml.example thorium-cluster.yml |
| 64 | +# edit thorium-cluster.yml as needed |
| 65 | +./deploy.sh |
109 | 66 | ``` |
110 | 67 |
|
111 | | -### Setup Tunnel (when using Thorium) |
| 68 | +If no `thorium-cluster.yml` exists, the script falls back to `thorium-cluster.yml.example`. |
112 | 69 |
|
113 | | -This is a blocking command that can must be run in a dedicated terminal window or put in the background. |
| 70 | +### Access Thorium |
| 71 | + |
| 72 | +Start the minikube tunnel in a separate terminal (this is a blocking command): |
114 | 73 |
|
115 | 74 | ```bash |
116 | | -minikube tunnel |
117 | | -# or ./expose |
| 75 | +./expose --help |
| 76 | +Usage: ./expose [--dev] [--stop] [--status] |
| 77 | + --dev Also forward database ports (Elastic, Kibana, Redis, MinIO, Scylla) |
| 78 | + --stop Stop all running port-forwards |
| 79 | + --status Show which port-forwards are running |
118 | 80 | ``` |
119 | 81 |
|
120 | | -### Setup Dev Tunnels (Elastic/Kibana, Scylla, Redis) |
| 82 | +Then open http://localhost in your browser and log in: |
| 83 | +- **Username:** `test` |
| 84 | +- **Password:** `INSECURE_DEV_PASSWORD` |
| 85 | + |
| 86 | +### Dev tunnels (Elastic/Kibana, Scylla, Redis) |
121 | 87 |
|
122 | | -This is a blocking command that can must be run in a dedicated terminal window or put in the background. |
| 88 | +To access backing services directly from your host (useful for debugging): |
123 | 89 |
|
124 | 90 | ```bash |
125 | | -./expose-dev |
| 91 | +./expose --dev |
126 | 92 | ``` |
127 | 93 |
|
128 | | -### Get Thorium admin password |
| 94 | +### Cleanup |
| 95 | + |
| 96 | +Remove all deployed resources (without deleting the minikube cluster itself): |
129 | 97 |
|
130 | 98 | ```bash |
131 | | -kubectl get secret -n thorium thorium-pass --template={{.data.thorium}} | base64 --decode; echo |
| 99 | +./cleanup |
132 | 100 | ``` |
133 | 101 |
|
134 | | -### Cleanup of Minithor |
| 102 | +To fully remove minikube: |
135 | 103 |
|
136 | 104 | ```bash |
137 | 105 | ./stop |
|
0 commit comments