Install and operate

Install Lagoria

This guide takes you from an empty AWS account to a running Lagoria. You start Lagoria Control on your machine, answer five short steps in the browser, and it deploys everything. Plan for about an hour, most of it waiting for AWS.

Before you start#

Do these once per AWS account. Most of them take a few minutes; the first one can take up to two hours on a brand-new account.

An AWS account in eu-central-1#

Use an account dedicated to Lagoria if you can. Lagoria is deployed to eu-central-1 (Frankfurt).

A machine with Docker#

Linux, macOS, or Windows with WSL2, with Docker installed. Lagoria Control runs there; it needs internet access to reach AWS, and the machine must stay awake during the deploy.

AWS credentials#

Administrator rights in the account, for install and upgrades. Either:

• an AWS CLI profile in your ~/.aws folder. IAM Identity Center (SSO) works: run aws sso login --profile <name> first; or
• an access key you paste into Lagoria Control. It stays in memory and is never written to disk.

Accept Claude Sonnet 4.6 once#

Lagoria's chat uses Anthropic's Claude Sonnet 4.6 through Amazon Bedrock. Anthropic's terms have to be accepted once per account, by an administrator:

1. In the AWS console, switch to eu-central-1 and open Amazon Bedrock → Model catalog → Claude Sonnet 4.6.
2. Choose Open in playground. If a form asks for Anthropic use-case details, fill it in and submit it.
3. Send a short message, such as "hi". When Claude answers, the account is subscribed.

It can take a few minutes before the check in Lagoria Control sees the agreement as accepted. The Cohere models used for search are accepted automatically during the deploy.

Optional: single sign-on#

To let people sign in with their work accounts, register an OIDC application in Microsoft Entra ID or Keycloak and have its issuer URL, client ID and client secret ready. You register Lagoria's redirect URI in that application after the first deploy; Lagoria Control shows it.

Optional: your own domain#

Lagoria gets an AWS address automatically. To use your own, such as lagoria.example.com:

• If the domain's DNS zone is in Route 53 in the same account, everything is automatic.
• Otherwise the deploy lists two DNS records for your DNS team to add.

Get the image#

We send you the version to install, for example 1.0.0, and either registry access or an offline file.

From our registry#

We allow your AWS account ID to pull. Sign in to the registry and pull:

aws ecr get-login-password --region eu-central-1 | docker login --username AWS --password-stdin <registry>
docker pull <registry>/lagoria-control:<version>

Optionally check that the image is signed by Lagoria's release process:

cosign verify <registry>/lagoria-control:<version> \
  --certificate-oidc-issuer https://token.actions.githubusercontent.com \
  --certificate-identity-regexp '^https://github.com/Algoria-labs/eip-monorepo/'

Offline#

For machines that cannot reach our registry, check and load the file we send:

sha256sum -c lagoria-control-<version>.tar.gz.sha256
docker load -i lagoria-control-<version>.tar.gz

Start Lagoria Control#

Create a working folder. Lagoria Control keeps its settings (never secrets) and an activity log there, so use the same folder every time.

mkdir -p ~/lagoria-control && cd ~/lagoria-control

docker run --rm -it -p 127.0.0.1:8080:8080 \
  -v "$HOME/.aws:/home/lagoria/.aws" \
  -v "$PWD:/work" \
  lagoria-control:<version>

On Linux, add --user "$(id -u):$(id -g)" so the container can read your ~/.aws files.

It prints a link such as http://127.0.0.1:8080/?token=…. Open it in your browser. The token changes every time you start the container, and the page is only reachable from your own machine. Press Ctrl+C in the terminal to stop Lagoria Control.

Walk through the setup#

1. Welcome#

   The first screen shows which version this image installs. Choose Let's set it up.

   

2. AWS access#

   Choose how Lagoria Control reaches your account:

   • Mounted profile: pick a profile from your ~/.aws folder.
   • Access keys: paste an access key ID, secret and, if you have one, a session token.

   Leave the region at eu-central-1 and choose Check access. Lagoria Control shows the account and identity it connected as.

   

   Check the account

   Everything that follows is deployed into the account shown here. If it is not the right one, pick another profile.

3. Environment#

   Describe the environment. These settings are saved in your working folder.

   Field	What to enter
   App name	A short lowercase name, such as lagoria. It names the Amplify app; keep it the same for every upgrade.
   Branch	The environment's branch name, such as main. Keep it the same as well.
   Region	eu-central-1.
   Custom domain	Optional. The full address, such as https://lagoria.example.com.
   Owner emails	The people who may claim admin the first time they sign in. Separate several with commas.
   Alert email	Optional. Where CloudWatch alarms are sent.
   Knowledge graph	Off by default. It adds Amazon Neptune, which costs more. If you turn it on, also turn on Stop the graph out of hours to save cost.

   

4. Sign-in#

   Choose how people sign in: None (Lagoria's own sign-in page), Microsoft Entra ID or Keycloak. For Entra ID or Keycloak, enter the issuer URL, then paste the client ID and client secret and choose Store next to each.

   The client ID and secret are kept in Lagoria Control's memory and written to AWS Systems Manager Parameter Store (encrypted) in your account during the deploy. They are never shown again.

   

5. Checks#

   Lagoria Control checks the account before anything is changed:

   • Failed (red) stops the deploy. Each one says what to do; fix it and choose Run again.
   • Warning (amber) does not stop the deploy. Read it, then continue.

   

   Check	If it does not pass
   AWS credentials	Go back to AWS access and connect again. For SSO, run aws sso login first.
   Region	Use the same region in AWS access and in the environment.
   Permissions	A warning only. The deploy names any missing permission if there is one.
   Claude Sonnet 4.6	Accept it once in the Bedrock console (see Before you start), wait a few minutes, run the checks again.
   Cohere models	Nothing to do: the deploy accepts them.
   Identity provider	Check the issuer URL, and that it is reachable from your machine.
   Existing installation	Shows what this image will do: install, upgrade, reinstall, or why it refuses.

6. Deploy#

   Lagoria Control shows the plan: what it will do and to which version. Choose Install, then confirm.

   

   The deploy then runs on its own. You can follow it three ways:

   • the steps along the top, each turning green as it finishes;
   • the diagram of Lagoria's parts, which light up as they are built;
   • the log underneath, with every line AWS reports.

   

   A first install takes about 30 to 45 minutes, most of it in Deploy the backend while AWS creates the search collection and the knowledge base. What each step does:

   Step	What happens
   Check credentials and plan	Confirms the account and what will be installed.
   CDK bootstrap	Prepares the account for deployments, the first time only.
   Create or find the Amplify app and branch	Creates the app that hosts Lagoria.
   Write environment variables	Saves your settings on the app. Settings made inside Lagoria, such as connectors, are kept.
   Write secrets	Stores the sign-in client ID and secret, encrypted.
   Back up data tables	On upgrades: backs up every DynamoDB table first. Skipped on a first install.
   Wake the graph database	If the graph is parked by its schedule, starts it; a stopped database cannot be updated.
   Deploy the backend	Creates or updates every AWS resource.
   Upload the web app	Publishes the web app.
   Attach the custom domain	Connects your domain, if you set one.
   Verify the deployment	Checks that the site, its configuration and the API answer, and that the API refuses anonymous calls.
   Record the release	Stores the installed version in your account, for future upgrades.

   Keep the machine awake

   Lagoria Control drives the deploy from your machine. If it sleeps, AWS keeps building, but the last steps wait. On a Mac, run caffeinate -dims in another terminal and keep the lid open.

   If the deploy is interrupted, start Lagoria Control again and deploy again. It is safe to repeat: finished work is reused.

   When every step is green, the deploy is done.

   

After the install#

Open Lagoria#

The Overview shows Lagoria's address. If you set a custom domain, its certificate can take up to about 30 minutes; until then the Overview also shows the AWS address, which works straight away.

Register the redirect URI#

If you chose Entra ID or Keycloak, open Configuration in Lagoria Control and copy the redirect URI. Add it to the OIDC application in your identity provider. Until you do, sign-in through it fails with a redirect mismatch.

First sign-in#

A new Lagoria has no users. The owner emails you entered can sign in and claim admin. From there, admins invite others and set up connectors inside Lagoria.

Connectors#

Connectors (Confluence, Jira, ServiceNow, OneDrive, Google Drive, Figma and others) are set up inside Lagoria, not in Lagoria Control. On a new install they start as requires setup.