> For the complete documentation index, see [llms.txt](https://docs.loci-dev.net/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.loci-dev.net/self-hosted/deployment-guide.md).

# Deployment Guide

### 1. Purpose <a href="#id-1.-purpose" id="id-1.-purpose"></a>

This page describes how to deploy the **LOCI** platform as a self-hosted (on-prem in your AWS account) installation using the provided **loci-box** package and **LOCI bootstrapper Docker image**.

The guide is intended for DevOps / Cloud engineers who have admin access to the target AWS account.

***

### 2. Prerequisites <a href="#id-2.-prerequisites" id="id-2.-prerequisites"></a>

Before you begin, make sure you have all of the following.

#### 2.1 AWS & Permissions <a href="#id-2.1-aws-and-permissions" id="id-2.1-aws-and-permissions"></a>

* An **AWS account** dedicated to the LOCI deployment (recommended).
* An **IAM user** or role with **AdministratorAccess** or equivalent permissions, including:
  * Full access to **ECR**, **EC2**, **VPC**, **IAM**, **CloudWatch**, **S3**, and any other LOCI-related services.
* Valid **AWS credentials** configured on the machine that will run the bootstrap container (e.g. via `aws configure` or assumed role).

#### 2.2 DNS (optional) <a href="#id-2.2-aws-dns-hosted-zone" id="id-2.2-aws-dns-hosted-zone"></a>

* A public Route 53 Hosted Zone is not required. By default, frontend/backend/Grafana are reached via ALB DNS names with a self-signed HTTPS certificate.\
  If you want a custom domain, you may use any DNS provider (AWS Route 53 or external) and optionally provide ACM certificate ARNs in `config.ini`.

#### 2.3 LOCI Assets <a href="#id-2.3-loci-assets" id="id-2.3-loci-assets"></a>

You should receive the following from the LOCI team:

* **LOCI installation key**\
  Used to authenticate and authorize your deployment.
* `loci-box.zip` **or** `loci-box.tar`\
  This archive contains:
  * `config.ini.sample` (or similar sample configuration file)
  * **This installation document** (or a link to it)
  * **Installation key file** (if provided as a file)
  * Any additional helper scripts or notes (if applicable)

> **Note:** Keep the installation key and archive in a secure location. They are unique to your organization.

#### 2.4 Local Environment <a href="#id-2.4-local-environment" id="id-2.4-local-environment"></a>

* A Linux / macOS / Windows host with:
  * **Docker** installed and running
  * Network access to:
    * `258916827218.dkr.ecr.us-east-1.amazonaws.com` (LOCI ECR)
    * Standard AWS service endpoints (EC2, VPC, IAM, etc.)
* Ability to download and unpack `zip` or `tar` archives.

***

### 3. High-Level Deployment Flow <a href="#id-3.-high-level-deployment-flow" id="id-3.-high-level-deployment-flow"></a>

1. Prepare an AWS admin user/role and configure credentials locally.
2. Unpack `loci-box.zip` / `loci-box.tar`.
3. Edit `config.ini` based on your environment and the sample file.
4. Pull and run the **LOCI bootstrapper** Docker image:
   * `258916827218.dkr.ecr.us-east-1.amazonaws.com/loci-infra:latest`
5. Wait for the deployment to complete (about **30 minutes**).
6. Perform validation checks:
   * Access to LOCI main web UI
   * Access to LOCI monitoring URL
   * Billing/Cost tags applied to infrastructure
7. If anything fails or seems unclear, contact LOCI Support.

***

### 4. Unpack LOCI Box & Prepare `config.ini` <a href="#id-4.-unpack-loci-box-and-prepare-config.ini" id="id-4.-unpack-loci-box-and-prepare-config.ini"></a>

1. Copy `loci-box.zip` / `loci-box.tar` to your deployment machine.
2. Extract the archive, for example:

   `# For tar tar -xvf loci-box.tar # For zip unzip loci-box.zip`
3. Inside the extracted directory you should see a **sample** `config.ini` file.
4. Create your working config file:

   `cp config.ini.sample config.ini`
5. Open `config.ini` in your preferred editor and update values as needed (AWS region, account details, networking preferences, installation key, etc.).

> **Important:**
>
> * Every field in `config.ini` is documented inline in the file.
> * Make sure all required values are filled in before starting the bootstrapper.
> * Keep your installation key and any secrets **out of version control**.

***

### 5. Pull and Run the LOCI Bootstrapper <a href="#id-5.-pull-and-run-the-loci-bootstrapper" id="id-5.-pull-and-run-the-loci-bootstrapper"></a>

#### 5.1 Set Helpful Environment Variables <a href="#id-5.1-set-helpful-environment-variables" id="id-5.1-set-helpful-environment-variables"></a>

From the folder where `config.ini` is located:

`export IMAGE_NAME="258916827218.dkr.ecr.us-east-1.amazonaws.com/loci-infra:latest" export CONTAINER_NAME="loci-bootstrapper"`

If your environment requires explicit ECR login, ensure you are authenticated to the ECR registry (example using AWS CLI v2):

`aws ecr get-login-password --region us-east-1 \ | docker login \ --username AWS \ --password-stdin 258916827218.dkr.ecr.us-east-1.amazonaws.com`

#### 5.2 Run the Bootstrapper and Deploy <a href="#id-5.2-run-the-bootstrapper-and-deploy" id="id-5.2-run-the-bootstrapper-and-deploy"></a>

Run the LOCI bootstrapper container in detached mode:

`docker run -d \ --name "${CONTAINER_NAME}" \ -v "$(pwd)/config.ini:/workspace/scripts/config.ini:ro" \ "${IMAGE_NAME}" --deploy`

* `-d` – runs the container in the background.
* `--name` – gives a friendly name to the container to reference later.
* `-v "$(pwd)/config.ini:/workspace/scripts/config.ini:ro"` – mounts your local `config.ini` into the container in **read-only** mode.
* `"${IMAGE_NAME}"` – the LOCI bootstrapper image.
* `--deploy` Begin deployment

#### 5.3 Monitor Deployment Progress <a href="#id-5.3-monitor-deployment-progress" id="id-5.3-monitor-deployment-progress"></a>

The deployment typically takes **around 30 minutes**.

To monitor progress:

`docker logs -f "${CONTAINER_NAME}"`

* Look for messages indicating successful creation/configuration of infrastructure resources.
* If you see obvious errors (e.g., missing config fields or AWS permission issues), stop and fix the cause, then re-run the container if needed.

***

### 6. Post-Deployment Validation <a href="#id-6.-post-deployment-validation" id="id-6.-post-deployment-validation"></a>

After the bootstrapper finishes successfully, perform the following checks.

> The exact URLs and identifiers will be provided to you as part of the LOCI onboarding or visible in the bootstrapper logs.

#### 6.1 Application UI <a href="#id-6.1-application-ui" id="id-6.1-application-ui"></a>

* Open a browser and navigate to the **main LOCI platform URL**(as populated on config.ini)
* Verify:
  * Login page or landing page loads correctly.
  * No obvious errors appear in the UI.
  * You can log in (if initial admin credentials were provided).
  * Upload sample binary provided with the loci-box and wait for successful analysis

#### 6.2 Monitoring & Observability <a href="#id-6.2-monitoring-and-observability" id="id-6.2-monitoring-and-observability"></a>

* Navigate to the main **monitoring URL** (e.g., Grafana/monitoring endpoint provided during setup).
* Verify:
  * The dashboards are accessible.
  * Basic system health panels show data (CPU, memory, key LOCI services).

#### 6.3 Billing & Tags <a href="#id-6.3-billing-and-tags" id="id-6.3-billing-and-tags"></a>

Verify that **billing tags** are applied to all LOCI infrastructure resources, according to your organization’s cost allocation standards. For example:

* In the AWS console, open the Cost Explorer and look for LOCI under tags menu,

***

### 7. Support & Contact <a href="#id-7.-support-and-contact" id="id-7.-support-and-contact"></a>

If any step fails, or if the platform does not behave as expected after deployment:

* Collect:
  * The **docker logs** of the bootstrapper container.
  * Any relevant error messages from the AWS console.
  * A brief description of what you tried and where it failed.

Then contact the **LOCI Support team**:

* 📧 Support email: *(<support@auroralabs.com>)*

> We’re here to help – if something goes wrong, don’t hesitate to reach out. The LOCI team will assist you in troubleshooting and completing your deployment successfully.