docs: separate public manual from internal project documentation
Publish documentation / publish (push) Successful in 27s
Publish documentation / publish (push) Successful in 27s
This commit is contained in:
Codex
+47
-81
@@ -1,98 +1,64 @@
|
||||
# Install and first start
|
||||
|
||||
For the ordered clone-to-start procedure on Mac, Windows WSL2 and Linux, use the
|
||||
[Italian manual guide](standalone-manual-it.md) or [English manual guide](standalone-manual-en.md),
|
||||
including protected credentials and the explicit initial catalog migration.
|
||||
Use one complete procedure for a fresh installation:
|
||||
|
||||
This is the supported local installation path. It creates an installation-local configuration and
|
||||
starts the Compose stack; it does not create a workspace repository or a database catalog entry.
|
||||
- [Italian manual installation](standalone-manual-it.md)
|
||||
- [English manual installation](standalone-manual-en.md)
|
||||
|
||||
## Prerequisites and boundaries
|
||||
Both cover macOS, Windows through Ubuntu WSL2, and Linux. They use a Gitea clone,
|
||||
protected local configuration and manual terminal commands, without an application
|
||||
installer or launcher. See their verification matrix for tests still pending.
|
||||
|
||||
Install Docker Engine with Compose v2, plus the host `tht` command. On macOS or Linux, install the
|
||||
host command from the repository with `./scripts/install-tht.sh`; Windows uses
|
||||
`./scripts/install-tht.ps1`. The installer builds or verifies the native command and checks that
|
||||
`tht` is resolvable on `PATH`.
|
||||
## What must be ready
|
||||
|
||||
The stack contains `frontend`, `core`, `catalog-db`, `qdrant`, `embedding`, and the one-shot
|
||||
`embedding-model-init` and `catalog-migrate` services. DWH and model-provider endpoints are
|
||||
external installation settings. Pi runs inside `core`; do not install a host Pi executable for
|
||||
the application runtime.
|
||||
You need Docker with Compose, the host operator command `tht`, access to the workspace
|
||||
repository, and the credentials and network routes for the configured DWH and model
|
||||
providers. Pi runs inside the application runtime; no host Pi installation is needed.
|
||||
|
||||
Secrets, certificates, Pi authentication, and workspace endpoint bindings are protected
|
||||
installation-local files. Never put them in a workspace descriptor, an env file intended for
|
||||
version control, a URL, or a command line.
|
||||
The stack includes `frontend`, `core`, `catalog-db`, `qdrant`, `embedding`, plus the
|
||||
one-shot `embedding-model-init` and `catalog-migrate` services. DWH and generative-model
|
||||
endpoints remain separate installation settings.
|
||||
|
||||
## Create the local installation
|
||||
Secrets, certificates, Pi authentication and endpoint bindings are protected local files.
|
||||
Do not commit them or copy the configuration of another machine unchanged.
|
||||
|
||||
From the repository root, start the interactive setup and select the local profile:
|
||||
## Follow the ordered procedure
|
||||
|
||||
The bilingual guides provide the exact commands for:
|
||||
|
||||
1. Cloning the selected revision and checking prerequisites.
|
||||
2. Bootstrapping the native host command.
|
||||
3. Preparing catalog passwords and using
|
||||
`tht setup --profile local --shell-mode full --shell-default-locale en --configure-only`.
|
||||
4. Completing model, authentication and workspace credentials.
|
||||
5. Generating configuration, building images and explicitly running `catalog-migrate`.
|
||||
6. Starting the installation and checking health and readiness.
|
||||
|
||||
Do not run setup alone as a substitute for that sequence. Migrations are not an
|
||||
implicit effect of backend startup or `tht start`. Do not mix this installation's
|
||||
descriptor/project with a different low-level Compose environment.
|
||||
|
||||
For an already configured installation:
|
||||
|
||||
```sh
|
||||
tht setup --profile local --shell-mode full --shell-default-locale en
|
||||
```
|
||||
|
||||
It writes the selected non-secret descriptor below `deploy/<installation-id>/`, the associated
|
||||
operator env file, and can create protected secret templates. Keep the descriptor path: pass it
|
||||
to commands as `--installation /absolute/path/thothii-installation.yaml` when more than one
|
||||
installation can be discovered.
|
||||
|
||||
The explicit shell options are important: compatibility defaults without them
|
||||
are embedded/en/omics-portal, which expects an Omics document. The Mac's standalone
|
||||
installation must use full, with English as its initial locale. Existing browser
|
||||
language preferences take precedence over that initial value. Full does not
|
||||
configure authentication; setup separately bootstraps local login.
|
||||
|
||||
For a server portal, use the [embedded/upstream procedure](authentication-upstream.md)
|
||||
instead of creating a second ThothII login. For a standalone server, use full
|
||||
with [direct OIDC](authentication-oidc.md). Shell mode does not follow `profile`
|
||||
automatically. See [configuration and regeneration](../operations/shell-and-localization.md)
|
||||
before modifying an existing installation.
|
||||
|
||||
If the descriptor is prepared manually instead, begin with
|
||||
[`thothii-installation.local.yaml`](examples/thothii-installation.local.yaml), set mode `0600` or
|
||||
`0400`, and ensure `THT_INSTALLATION_CONFIG_SOURCE` in the selected env file points to that exact
|
||||
file. Create the secret bundle from `deploy/secrets/thothii.secrets.example`, protect it, and set
|
||||
the file locations and external endpoints in the env file. The required settings include:
|
||||
|
||||
- `PI_AUTH_FILE`, `THT_SECRETS_FILE`, and the catalog password source files;
|
||||
- `THT_INSTALLATION_CONFIG_SOURCE` and the workspace Git remote/branch;
|
||||
- the DWH and model-provider endpoints; and
|
||||
- `THT_AUTH_CONFIG_ROOT` for local authentication or the OIDC configuration selected during setup.
|
||||
|
||||
For the supported secret names and the metadata-generation model credential boundary, see the
|
||||
`deploy/secrets/README.md` file in the installation checkout. It is intentionally not published
|
||||
as a documentation page because it describes a protected local-file contract.
|
||||
|
||||
## Start and verify
|
||||
|
||||
For the normal local path, use the launcher:
|
||||
|
||||
```sh
|
||||
./scripts/run-stack.sh
|
||||
```
|
||||
|
||||
It builds `core`, starts `catalog-db`, runs `catalog-migrate`, then keeps the base plus local
|
||||
Compose profile in the foreground. Database migrations are deliberately not a hidden backend
|
||||
startup action. Open `http://127.0.0.1:8080` unless `THOTH_HTTP_PORT` was changed.
|
||||
|
||||
In another terminal, verify the installation without changing it:
|
||||
|
||||
```sh
|
||||
tht --installation /absolute/path/thothii-installation.yaml doctor --json
|
||||
tht --installation /absolute/path/thothii-installation.yaml status
|
||||
tht --installation /absolute/path/thothii-installation.yaml doctor --json
|
||||
```
|
||||
|
||||
`/health` verifies application-process readiness; `tht doctor` is the diagnostic surface for
|
||||
Compose, configuration, workspace, workflow, and Pi prerequisites.
|
||||
`/health` checks application-process readiness. Doctor also checks configuration,
|
||||
workspace, workflow and Pi prerequisites; a healthy web page alone does not prove
|
||||
that a real database question can complete.
|
||||
|
||||
## Routine lifecycle and next steps
|
||||
## After startup
|
||||
|
||||
Use `tht start [--build]`, `tht stop`, `tht logs`, and `tht doctor` rather than composing ad-hoc
|
||||
container commands. Named volumes retain settings, Pi state, workspace registry, sessions,
|
||||
Qdrant data, and embedding models across `docker compose down`; removing them requires the
|
||||
explicit destructive `--volumes` form.
|
||||
Prepare [workspaces](../operations/workspaces.md), configure a database in
|
||||
[Database Management](../operations/database-management.md), and complete the functional
|
||||
checks in the installation guide before using real data.
|
||||
|
||||
After the stack is healthy, configure authentication if setup did not do so, then continue with
|
||||
[Workspace operations](../operations/workspaces.md). For server profile, reverse proxy, backups,
|
||||
and recovery, use the deployment program and its manual gates; the server profile is not a
|
||||
drop-in replacement for the local command above.
|
||||
See [display mode and language](shell-and-language.md), [local authentication](authentication-local.md),
|
||||
[OIDC](authentication-oidc.md) and [model configuration](../general/pi-configuration.md)
|
||||
for later changes. Embedded portal integration is separate from a fresh standalone setup.
|
||||
|
||||
Use the installation's normal `tht start`, `tht stop` and diagnostic commands.
|
||||
Preserve its descriptor, credentials, database and persistent volumes; do not use
|
||||
`down --volumes` as a routine stop or upgrade.
|
||||
|
||||
Reference in New Issue
Block a user