| name | hydraide-install-and-upgrade |
| description | Installing, upgrading, and bootstrapping HydrAIDE. Server install on Linux as a systemd service, Docker install for dev or production, Go SDK install in your application, server and SDK upgrades, V1 to V2 storage migration, filesystem and hardware guidance, and troubleshooting common install errors. Use when starting fresh with HydrAIDE, picking an install method, upgrading the server or the SDK, planning a storage migration, or hitting install or setup errors. For day-to-day server operations after install, use the `hydraidectl` skill. For Go application code that uses the SDK, use the `hydraidego` skill. For conceptual questions about how the engine works, use the `hydraide` skill. |
HydrAIDE Install and Upgrade
This skill is a router. Pick the matching topic, read the linked doc, and answer grounded in it. Do not fabricate install steps or version numbers from memory.
When to use this skill vs. its siblings
| User's question shape | Skill |
|---|
| "How do I install HydrAIDE", "upgrade the server", "migrate V1 to V2", "go get the SDK", "Docker compose for HydrAIDE" | hydraide-install-and-upgrade (this skill) |
| "Manage a running instance", "stop/start/restart", "backup/restore", "observe", "compact", "explore" | hydraidectl |
"Write Go code that ...", "model this in hydraidego", "what filter do I use for ..." | hydraidego |
| "Explain how X works", "Why does HydrAIDE do Y" | hydraide |
Quick decision: which install path?
| Goal | Path |
|---|
| Try HydrAIDE locally in 2 minutes | Docker compose quickstart from the example tree (server + auto-generated TLS certs) |
| Production server on Linux | hydraidectl single-binary install with a systemd unit |
| Production server in containers | Docker install with the published ghcr.io/hydraide/hydraide image |
| Add the Go SDK to my application | go get github.com/hydraide/hydraide/sdk/go/hydraidego/v3@latest |
| Upgrade an existing HydrAIDE server | server upgrade page (rolling vs full restart, version compat) |
| Upgrade the Go SDK in my application | go get -u, with the version-compatibility table |
| Move a v1 storage to v3 | V1 to V2 storage migration before upgrading the running server |
| Pick a filesystem or hardware for production | filesystem and hardware guidance |
| Contribute to HydrAIDE itself | contributor setup with go.work and the replace directive |
Topic index
| Topic | When the user is asking about... | Read |
|---|
| Filesystem and hardware guidance | "What filesystem", "what disk", "production hardware", "ext4 vs xfs vs zfs", IOPS budgeting | docs/install/README.md |
| Linux quickstart | First-time install on a Linux host, end-to-end | docs/install/quickstart.md |
| Docker install (dev or prod) | docker-compose.yml, image tag, persistent volumes, certs in containers | docs/install/docker-install.md |
hydraidectl install (the CLI itself) | Installing the hydraidectl management binary on the host that runs the server | docs/hydraidectl/hydraidectl-install.md |
| Go SDK install + upgrade | go get, pinned versions, upgrade command, version compatibility, troubleshooting | docs/sdk/go/install.md |
| HydrAIDE contributor setup | Working on HydrAIDE itself: go.work, replace directive, day-to-day build/test, release flow | docs/sdk/go/contributor-setup.md |
| Server upgrade | Bumping the running HydrAIDE server to a newer version, downtime planning | docs/hydraidectl/upgrades.md |
| V1 to V2 storage migration | Moving from the legacy chunk-folder layout to the v2 single-file .hyd format. Required before running on v3 against v1 data | docs/hydraidectl/hydraidectl-migration.md |
Version compatibility (cheat sheet)
| Server | Compatible Go SDK |
|---|
server/v3.x | sdk/go/hydraidego/v3.x |
The major version of the SDK matches the major version of the server era. A v3 SDK can talk to any v3 server release. Cross-major compatibility is not guaranteed; bump server and SDK in lockstep when crossing a major.
How to answer
- Match the user's intent to one row in the topic index.
- Read the linked file. The plugin keeps these mirrored, so the path resolves locally.
- Answer the user's actual question, grounded in the file. Quote sparingly; explain in your own words.
- If the topic spans two docs (for example, "I'm doing a clean Linux install AND I have v1 data"), read both and sequence the steps: filesystem and hardware guidance first, then quickstart, then migration.
- If the user wants code or runtime configuration after install, hand off:
- Operating the server day-to-day:
hydraidectl skill.
- Writing Go application code:
hydraidego skill.
Common install pitfalls (quick reference)
- TLS cert mismatch: the
ServerName your client passes must match the CN of the certificate (default hydraide). Easy to miss when copying configs between environments.
hydraidectl init skipped on production: the systemd unit lives in a known location and the binary expects specific permissions. Re-run hydraidectl init -i <name> if the install is in a half-finished state, do not hand-edit the unit file.- Docker compose stack vs published image:
docs/sdk/go/examples/Dockerfile.dev builds the server straight from the in-repo source. The compose stack in the example tree uses that image, so it always matches the SDK in the same checkout. The published image (ghcr.io/hydraide/hydraide:latest) lags by the release cadence and may not have unreleased features.
- Forgot the SDK upgrade after a server major bump: server users on a new major need a matching SDK major or filter / patch behaviour can drift silently. Bump both.
go get against a fresh tag returns 410 Gone: the proxy has not cached the new version yet. Wait a minute, or run GOPROXY=direct go get ... once to force a direct pull.- V1 to V2 migration on a running server: do not. Stop the server, run
hydraidectl migrate, then start the server again. The migration is offline.
What this skill is not
- Not the day-to-day operations manual. Once installed, switch to
hydraidectl for stop/start/restart, backup/restore, observe, compact, explore.
- Not application code generation. For "create a Profile or Catalog model", switch to
hydraidego (or run the /hydraide-new-model slash command).
- Not a place to invent versions. If the user asks about a specific version compatibility that is not in the cheat sheet, read the upgrade or install doc; do not guess.
