Install SecureMind

Before you begin

• Git

  Downloads the code.

  git --version

• Docker with Compose v2

  Runs the app, the database, sign-in and the local models. On Windows and Mac, install Docker Desktop and leave it running.

  docker compose version

• 8 GB of free disk space

  Holds the images and the two local models (llama3.2:3b and nomic-embed-text).

• 8 GB of memory

  The practical minimum for the local chat model.

• Free ports

  3000 (app), 5432 (database), 4566 (sign-in) and 11434 (local models).

Install

1. 1

   Get the codeRequired

   Download the repository and open the folder.

   TerminalCopy

   git clone https://github.com/OrieBound/securemind.git
   cd securemind

2. 2

   Start SecureMindRequired

   Builds the app and starts the database, the sign-in service and the local models.

   TerminalCopy

   docker compose up --build

   Expected result. The first start downloads the local models and sets up the database, so it takes a while. Later starts are quick. In a second terminal, docker compose ps shows the app as healthy when it is ready.

   Prefer not to build it?

   Download the ready-made image instead of building it. It is built for 64-bit Intel and AMD computers. On an Apple Silicon Mac, use the build command above instead, so the image is made for your processor:

   TerminalCopy

   docker compose -f docker-compose.yml -f docker-compose.pull.yml pull
   docker compose -f docker-compose.yml -f docker-compose.pull.yml up --no-build

3. 3

   Open SecureMindRequired

   Go to http://localhost:3000 in your browser.

   Expected result. The sign-in page appears.

4. 4

   Create the first OwnerRequired

   Enter an email address and a password you choose. The first account becomes the Owner and can invite other people later. There is no demo account.

   No setup code on this install

   The setup code in the AWS guide is for the hosted install only. On your own computer, the first person to create an account is the Owner. Nothing else has to be printed or copied.
5. 5

   Connect a modelRecommended

   The local models work straight away, but they use your computer's own resources and are slow on most machines. An API key is strongly recommended. Sign in, open Settings → Models and paste a key from Groq (it has a free tier), Anthropic, OpenAI, Gemini or Grok. You can also connect Amazon Bedrock.

   Expected result. The key shows as Connected and its models appear in the list.

Stop, update or remove

docker compose down

git pull
docker compose up --build --no-deps --exit-code-from init init
docker compose up -d --build --no-deps --wait app

docker compose down -v

If something goes wrong

More detail, including backups, is in the Docker install guide in the repository.

Before you begin

• An AWS account you administer

  Owns everything that gets created. Use your own account, not an organization's management account.

• Git

  Downloads the code.

  git --version

• Node.js 20 or newer

  Runs the helper scripts and builds the app.

  node --version

• AWS CLI v2

  Signs you in to AWS and runs commands against it.

  aws --version

• Terraform 1.14 or newer

  Creates the AWS resources.

  terraform -version

• A GitHub account

  You need your own copy of the repository. The setup creates an AWS role that trusts that copy.

• Permission in the account

  To create IAM roles, S3 buckets, Lambda functions, API Gateway, Cognito, Amplify apps, DynamoDB tables and Systems Manager parameters. If you are the admin of your own account, you already have it.

• Recommended: Amazon Bedrock access

  Gives chat a model with no API key to paste. Strongly recommended on AWS, because there is no local model. You can add an API key in Settings instead.

What GitHub needs

A free GitHub account is enough. Set these up once, in this order:

1. A repository of your own that holds the code. Private is fine and recommended (step 1).
2. The AWS Amplify GitHub app, with your repository listed under Repository access (step 6).
3. Optional: a GitHub environment and a few variables, if you want GitHub Actions to run Terraform (step 4). Rulesets and branch protection are not required.
4. No AWS access key in GitHub, ever. Not as a secret and not as a variable.

Install

1. 1

   Make your own copy of the repositoryRequired

   Your AWS account builds from a repository you own. Make it private, so your settings and history stay yours. A fork of a public repository is always public, so create an empty repository and push the code to it instead.

   1. a

      Part a: Create an empty private repository

      On github.com/new, name it securemind, choose Private, and leave every box for adding a README, .gitignore or license unchecked.
   2. b

      Part b: Download the code and push it to your repository

      TerminalCopy

      git clone https://github.com/OrieBound/securemind.git
      cd securemind
      git remote set-url origin https://github.com/<your-github-username>/securemind.git
      git push -u origin main

   3. c

      Part c: Install the packages

      TerminalCopy

      npm install

2. 2

   Sign in to AWS with a named profileRequired

   A named profile means a command can never land in the wrong account by accident. If your account does not use AWS SSO, run aws configure --profile my-securemind instead.

   TerminalCopy

   aws sso login --profile my-securemind

   TerminalCopy

   aws sts get-caller-identity --profile my-securemind

   Expected result. The second command prints your Account number. Check that it is the account you intend to use. Every later command runs against it.

3. 3

   Bootstrap, onceRequired

   Creates a few small things: an S3 bucket for Terraform's own state, an IAM OIDC provider, one IAM role, and a permission boundary. Only your repository, running in one named GitHub environment, can assume the role. Nothing for the app itself exists yet. Choose a short name for this install, such as prod.

   Read your GitHub subject firstCopy

   gh api repos/<your-github-username>/securemind/actions/oidc/customization/sub --jq .sub_claim_prefix

   TerminalCopy

   cd infra/terraform/bootstrap
   terraform init
   terraform workspace new <env-name>
   terraform apply \
     -var="github_subject_prefix=<the value printed above>" \
     -var="env_name=<env-name>" \
     -var="github_environment=aws-<env-name>"

   TerminalCopy

   terraform output backend_hcl

   Expected result. Terraform shows a plan and asks you to type yes. The plan should list only the bucket, the OIDC provider, the role and the permission boundary. The subject you read ties the role to your repository alone, by the numeric IDs of your account and repository, so a copy of the code in anyone else's repository cannot use it. If the subject has no @ numbers in it, turn on immutable subjects for the repository first. Paste the output of the last command, as it is, into a new file at infra/terraform/backend.hcl. That file is git-ignored on purpose.

4. 4

   Add the GitHub variablesOptional

   Only needed if you want GitHub Actions in your repository to run Terraform for you. If you will only apply from your own computer, skip this whole step. Add every value as a variable, never as a secret.

   1. a

      Part a: Create the environment

      In your repository open Settings → Environments → New environment and name it exactly what you passed as github_environment in step 3, such as aws-<env-name>. Turn on Required reviewers, so you approve every run. GitHub only offers that on a public repository or a paid plan. On a free private repository, set Deployment branches to selected branches and allow only main.
   2. b

      Part b: Add these variables to that environment

      In the environment, under Environment variables:

      Variable	Value
      AWS_ROLE_ARN	The gha_role_arn output of step 3
      TF_STATE_BUCKET	The state_bucket output of step 3
      AWS_REGION	The region you deploy into, such as us-east-1
      PERMISSIONS_BOUNDARY_ARN	The permissions_boundary_arn output of step 3
      ENV_NAME	The <env-name> you chose in step 3

   3. c

      Part c: Add these variables to the repository

      Under Settings → Secrets and variables → Actions → Variables:

      Variable	Value
      AWS_ENVIRONMENT	The environment name from part a
      AWS_DEPLOY_ENABLED	true. Add this one last; it turns the Terraform jobs on.

   Never add an AWS access key

   Do not put AWS_ACCESS_KEY_ID or AWS_SECRET_ACCESS_KEY anywhere in GitHub. The role from step 3 is how GitHub signs in.
5. 5

   Configure and create the resourcesRequired

   Copy the example settings file to .env.deploy in the repository folder and fill in your values.

   TerminalCopy

   cp infra/env.deploy.example .env.deploy

   .env.deployCopy

   AWS_PROFILE="my-securemind"
   AWS_REGION="us-east-1"
   ENV_NAME="<env-name>"
   AMPLIFY_BRANCH="main"
   AUTH_MODE="cognito"
   AUTH_ALLOW_LOCAL_FALLBACK="false"

   TerminalCopy

   npm run infra:up

   Expected result. The command packages the two Lambda functions, runs Terraform and shows a plan. Type yes to continue. It then creates the Cognito sign-in pool, a DynamoDB table, the API, two Lambda functions and the Amplify app. Leave the other lines in the example file as they are.

   This step creates billable resources

   They can incur AWS charges while they exist. Step 11 shows how to remove them.
6. 6

   Connect Amplify to GitHubRequired

   Amplify hosts the web app. It needs to read your repository. The Amplify console wizard handles this, and it has four parts.

   1. a

      Part a: Let the Amplify GitHub app see your repository

      In GitHub open Settings → Applications → AWS Amplify (us-east-1) → Configure. If the app is not listed yet, the next part installs it. Under Repository access, add your securemind repository. Without this, the first build fails with a misleading IAM message.
   2. b

      Part b: Connect the repository in the console

      In the AWS console open Amplify → your app → Hosting, connect your GitHub repository through the GitHub App option (not a personal access token), and add the main branch.
   3. c

      Part c: Choose these wizard settings

      • Leave My app is a monorepo unchecked.
      • Leave Enable full-stack deploys unchecked.
      • For the service role, choose the existing securemind-amplify-<env-name> role. Do not let the wizard create a new one.
   4. d

      Part d: Switch auto-build off and re-apply the settings

      The wizard can turn auto-build on and reset values that Terraform set. Print the app ID first, then run the update.

      TerminalCopy

      terraform -chdir=infra/terraform output -raw amplify_app_id

      TerminalCopy

      aws amplify update-branch --app-id <amplify_app_id> --branch-name main --no-enable-auto-build --profile my-securemind --region us-east-1
      npm run infra:wire

7. 7

   Turn on Bedrock modelsRecommended

   An AWS install has no local model, so chat needs either Bedrock or an API key. Bedrock is strongly recommended, and it needs no key to paste. Open the Bedrock console in the same region, choose Model access, and request access to Titan Text Embeddings V2 and at least one chat model. This is a console setting. An IAM permission does not replace it.
8. 8

   Run the first buildRequired

   Auto-build is off, so you start the first build yourself. All three parts are required.

   1. a

      Part a: Start the build

      TerminalCopy

      aws amplify start-job --app-id <amplify_app_id> --branch-name main --job-type RELEASE --profile my-securemind --region us-east-1

   2. b

      Part b: Wait for it to finish

      In the Amplify console the build reaches SUCCEED. It usually takes a few minutes.
   3. c

      Part c: Check that the app is configured

      TerminalCopy

      terraform -chdir=infra/terraform output -raw amplify_default_domain

      TerminalCopy

      curl https://main.<amplify_default_domain>/api/setup/status

      Expected result. The reply shows "cognitoConfigured":true and "codeConfigured":true. If either is false, see the troubleshooting list below.

9. 9

   Create the first OwnerRequired

   The sign-in pool starts empty and there is no demo account. A hosted install is public on the internet, so the first account needs a one-time setup code. The code proves you are the person who created the install. It is not a password, and it is created by Terraform in step 5.

   1. a

      Part a: Print the setup code

      Copy the value it prints. The code exists only in Terraform's output and in an encrypted Parameter Store entry, never in the Amplify console.

      TerminalCopy

      terraform -chdir=infra/terraform output -raw setup_claim_secret

   2. b

      Part b: Open your Amplify address

      Go to https://main.<amplify_default_domain> from step 8. The first-run page asks for the setup code.
   3. c

      Part c: Enter the code, an email address and a password

      That account becomes the Owner and can invite other people. Once an Owner exists, the setup code stops working.
10. 10

    Sign in and connect a modelRequired

    Send a chat message. If you turned on Bedrock in step 7, it answers. If not, open Settings → Models and add an API key from Anthropic, OpenAI, Gemini, Groq or Grok.
11. 11

    Remove everything (when you are done)Optional

    Deletes the resources step 5 created. It leaves the small bootstrap bucket and the GitHub variables from steps 3 and 4. They are inert, and you can delete them by hand.

    TerminalCopy

    npm run infra:down -- --yes

If something goes wrong

Every command, with the reasoning behind each, is in the full AWS walkthrough in the repository. If a step here does not match what you see, open an issue with the step number.