257 lines
10 KiB
Markdown
257 lines
10 KiB
Markdown
# Guided standalone installation
|
|
|
|
[Versione italiana](standalone-manual-it.md)
|
|
|
|
This is the fresh-machine installation procedure for THothII. THothII receives a natural-language
|
|
question, queries an enterprise database read-only, and guides the user through SQL review. The
|
|
core, PostgreSQL catalog, Qdrant, embedding service, and Pi run in Docker; Node.js, Python, and Pi
|
|
are not required on the host.
|
|
|
|
## Before you start: the two repositories
|
|
|
|
There are two separate repositories:
|
|
|
|
1. the application repository cloned by the user:
|
|
https://git.tylconsulting.it/mptyl/ThothII.git;
|
|
2. the workspace repository supplied by the curator/installer. It is not the THothII repository
|
|
and must not be cloned inside the application directory.
|
|
|
|
The workspace repository normally contains:
|
|
|
|
~~~
|
|
thoth-workspaces.yaml
|
|
<workspace-id>/workspace.yaml
|
|
<workspace-id>/evidence/** # when Evidence is declared
|
|
~~~
|
|
|
|
workspace.yaml contains workspace identity, language and optional Evidence source. By design it does
|
|
not contain database passwords. Database identity, transport (PostgreSQL, REST, or tunnel), user,
|
|
password, token and certificates are installation-local settings stored encrypted by the Catalog.
|
|
This prevents credentials from being committed to the workspace repository.
|
|
|
|
## 0. Machine prerequisites
|
|
|
|
### Windows
|
|
|
|
- Windows 10/11 with Docker Desktop running and the WSL2 backend enabled.
|
|
- Ubuntu in WSL2, with Docker Desktop integration enabled for that distribution.
|
|
- Git, Bash, curl, OpenSSL and shasum inside WSL2.
|
|
- Do not install Node.js, Python or Pi on the host for this procedure.
|
|
|
|
If WSL2 is not installed, use the company procedure or, in PowerShell:
|
|
|
|
~~~
|
|
wsl --install -d Ubuntu
|
|
~~~
|
|
|
|
Run all commands inside Ubuntu WSL2, in a Linux directory such as $HOME/src, not under /mnt/c.
|
|
scripts/install-tht.ps1 exists for advanced native PowerShell scenarios; use WSL2 for the
|
|
reproducible test.
|
|
|
|
### macOS
|
|
|
|
- Docker Desktop installed and running, with several GB free for images and the embedding model.
|
|
- Git, Bash, curl, OpenSSL and shasum.
|
|
- Intel and Apple Silicon Macs are supported when Docker Desktop supports the architecture
|
|
reported by the Docker server.
|
|
- Do not install Node.js, Python or Pi on the host for this procedure.
|
|
|
|
### Linux, including Omarchy
|
|
|
|
- Git, Bash, curl, OpenSSL and shasum.
|
|
- Docker Engine and the Docker Compose v2 plugin. On Omarchy, check first:
|
|
|
|
~~~
|
|
command -v docker
|
|
docker compose version
|
|
docker info
|
|
~~~
|
|
|
|
If Docker is missing, install Docker and Compose using the distribution-approved package procedure,
|
|
then start the service. On an Arch-like distribution the typical route is:
|
|
|
|
~~~
|
|
sudo pacman -S docker docker-compose
|
|
sudo systemctl enable --now docker
|
|
sudo usermod -aG docker "$USER"
|
|
~~~
|
|
|
|
After adding the group, open a new session and repeat docker info. Node.js, Python and Pi are not
|
|
needed on the host: they are in the Docker images.
|
|
|
|
On every system run:
|
|
|
|
~~~
|
|
bash scripts/check-standalone-prerequisites.sh
|
|
docker version --format '{{.Server.Arch}}'
|
|
~~~
|
|
|
|
The architecture must be amd64, x86_64, arm64, or aarch64. You also need access to the
|
|
application Gitea repository, the workspace repository URL/branch and credentials, container
|
|
reachability to DWH/LLM endpoints, and the credentials, tokens or certificates associated with
|
|
the databases.
|
|
|
|
## 1. What to clone
|
|
|
|
Clone only the application:
|
|
|
|
~~~
|
|
mkdir -p "$HOME/src"
|
|
cd "$HOME/src"
|
|
git clone https://git.tylconsulting.it/mptyl/ThothII.git
|
|
cd ThothII
|
|
git rev-parse --short HEAD
|
|
~~~
|
|
|
|
Record the revision. tht setup --complete downloads the workspace repository into a persistent
|
|
Docker volume using the URL, branch and transport supplied during setup.
|
|
|
|
## 2. Install the terminal command
|
|
|
|
From the clone root:
|
|
|
|
~~~
|
|
bash scripts/check-standalone-prerequisites.sh
|
|
mkdir -p "$HOME/.local/bin"
|
|
THT_INSTALL_DIRECTORY="$HOME/.local/bin" bash scripts/install-tht.sh
|
|
export PATH="$HOME/.local/bin:$PATH"
|
|
tht version
|
|
~~~
|
|
|
|
tht is the only native component to install. It builds the binary with Docker and orchestrates
|
|
Compose; it is not a second application runtime.
|
|
|
|
## 3. Prepare a few secrets and run complete setup
|
|
|
|
The first execution creates protected placeholders under deploy/local/secrets/ and stops if a
|
|
required credential is missing. Fill in the requested files and rerun the same command; compatible
|
|
configuration files are reused.
|
|
|
|
~~~
|
|
tht setup --complete --profile local --shell-mode full --shell-default-locale en
|
|
~~~
|
|
|
|
The setup asks only for information the computer cannot know:
|
|
|
|
| Request | What to provide |
|
|
| --- | --- |
|
|
| Workspace repository | Data/configuration repository URL, not ThothII.git |
|
|
| Branch | normally main |
|
|
| Access | ssh with key and known_hosts, or https with credential file and CA |
|
|
| DWH/LLM URL | endpoint without a token in the URL |
|
|
| Local login | initial user and password requested by the prompt |
|
|
|
|
The setup generates random Catalog passwords and writes their paths, never their values, to
|
|
operator.env. It runs docker compose config, builds images, starts the Catalog, runs
|
|
catalog-migrate, starts the stack, and pulls the workspace repository. The pull also activates
|
|
declared Evidence; at minimum source files present in the workspace are materialized locally.
|
|
|
|
### The file the user fills in
|
|
|
|
The main file is:
|
|
|
|
~~~
|
|
deploy/local/secrets/thothii.secrets
|
|
~~~
|
|
|
|
Add only NAME=VALUE lines needed by modelCatalog and installation adapters, such as an LLM API key
|
|
(DEEPSEEK_API_KEY, OPENAI_API_KEY, or the key declared by the catalog) and, when applicable,
|
|
THT_DWH_API_KEY. Allowed names are documented in deploy/secrets/README.md. Never put tokens in
|
|
URLs, the repository, or copied shell commands.
|
|
|
|
Two distinctions prevent common errors:
|
|
|
|
- when the catalog uses pi_auth, the LLM token belongs in the Pi pi-auth.json file created by
|
|
setup; {} is only a placeholder and does not enable a model;
|
|
- workspace database credentials (PostgreSQL password, REST API token, tunnel SSH key,
|
|
known_hosts, CA) do not belong in the workspace repository. Enter them per workspace in
|
|
Database Management, which stores them encrypted in the Catalog. The workspace declares
|
|
database/schema and transport; the installer must obtain the actual values from the database owner.
|
|
|
|
A private workspace repository also needs the Git files required by its transport: an SSH key and
|
|
known_hosts, or an HTTPS credential file and CA. These are transport files, not a second bundle to
|
|
commit. To minimize manual files, use SSH with an already-authorized deploy key.
|
|
|
|
## 4. Automatic checks and terminal tests
|
|
|
|
Setup verifies files, permissions, descriptor, Compose, Docker, authentication, services, Pi and
|
|
the workspace. After startup, run these commands at any time:
|
|
|
|
~~~
|
|
INSTALLATION="$PWD/deploy/local/thothii-installation.yaml"
|
|
tht --installation "$INSTALLATION" doctor --json
|
|
tht --installation "$INSTALLATION" workspace pull --json
|
|
tht --installation "$INSTALLATION" workspace test --json
|
|
~~~
|
|
|
|
workspace test checks, for every active workspace, database binding and credentials, Evidence,
|
|
Qdrant, and the embedding service. It exits non-zero when the database binding is missing or a
|
|
connection is unusable. Before running it, the installer must configure the database in Database
|
|
Management: the workspace repository cannot contain the password by itself.
|
|
|
|
doctor --json is the repeatable, non-destructive core verification. The final functional test must
|
|
also open http://127.0.0.1:8080, sign in, and complete a real question through final SQL.
|
|
|
|
## Activities only the installer can complete
|
|
|
|
The procedure automates bootstrap, but it cannot invent enterprise decisions or authorizations.
|
|
The installer must complete and record:
|
|
|
|
1. usable LLMs, the modelCatalog, and linked API keys; then run tht pi test and tht doctor;
|
|
2. database configuration, connection test, schema synchronization, and description generation;
|
|
3. human consolidation of generated descriptions;
|
|
4. Qdrant semantic entries through workspace preprocess run;
|
|
5. naming-based FK suggestions as a complement to schema FKs, human review, and loading approved
|
|
relationships into Qdrant;
|
|
6. recurring tht doctor --json and tht workspace test --json checks;
|
|
7. one real question completed successfully without connection or model errors.
|
|
|
|
Configuration is complete only when all applicable activities are done, decisions are recorded, and
|
|
the two terminal tests are green. The core is usable only after the real question, not merely
|
|
because the frontend answers /health.
|
|
|
|
## Gate A and Gate B
|
|
|
|
### Gate A — platform
|
|
|
|
~~~
|
|
uname -a
|
|
docker version --format '{{.Server.Version}} {{.Server.Arch}}'
|
|
tht version
|
|
bash scripts/check-standalone-prerequisites.sh
|
|
bash scripts/verify-standalone-install.sh "$INSTALLATION"
|
|
~~~
|
|
|
|
### Gate B — usability
|
|
|
|
~~~
|
|
tht --installation "$INSTALLATION" doctor --json
|
|
tht --installation "$INSTALLATION" workspace test --json
|
|
curl --fail --silent --show-error http://127.0.0.1:8080/health
|
|
~~~
|
|
|
|
Then run a real question and stop/restart with tht stop and tht start. Do not use docker compose
|
|
down --volumes: it deletes the Catalog, sessions, Qdrant data and the embedding model.
|
|
|
|
## Quick diagnosis
|
|
|
|
| Symptom | Action |
|
|
| --- | --- |
|
|
| Docker Engine is not reachable | start Docker Desktop or systemctl and repeat docker info |
|
|
| Omarchy cannot find docker | install Docker/Compose, enable the service and open a new session |
|
|
| Windows sees Docker but Bash fails | use Ubuntu WSL2 and enable its Docker Desktop integration |
|
|
| workspace pull fails | check URL, branch, key/credential file and known_hosts from the container |
|
|
| workspace test reports a missing binding | configure database, token/password and CA in Database Management |
|
|
| Pi is not ready | fill pi-auth.json or the key declared by modelCatalog, then run tht pi test |
|
|
|
|
## Related documents
|
|
|
|
- [Install and first start](first-start.md)
|
|
- [Workspace operations](../operations/workspaces.md)
|
|
- [Database Management](../operations/database-management.md)
|
|
- [Model configuration](../general/pi-configuration.md)
|
|
- deploy/secrets/README.md
|
|
|
|
Publishing images on Docker Hub and native DMG/MSI/AppImage installers remain later work: this
|
|
procedure starts from the Gitea clone and does not require pre-published Docker Hub images.
|