# Nanome v2 Deployment

## Architecture Diagram ![](https://s3.us-west-1.amazonaws.com/nanome-outline-wiki/uploads/777abeaf-d331-463e-93b2-6059f282151a/4963ca9e-74c3-4688-9a1f-027659aeafc4/image.png?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Content-Sha256=UNSIGNED-PAYLOAD&X-Amz-Credential=AKIAWNVKRSKCPXL6TQZ2%2F20261104%2Fus-west-1%2Fs3%2Faws4_request&X-Amz-Date=20261104T013000Z&X-Amz-Expires=86400&X-Amz-Signature=62ebdc3636b43692ff26f6a13c364501b57669344c93f85e526295925f11bca4&X-Amz-SignedHeaders=host&x-amz-checksum-mode=ENABLED&x-id=GetObject " =1352x1192")


## Requirements

Specs are highly variable to customer compute needs


---

#### Linux VM min-spec (VM1)

* t3.large EC2 or equivalent
* 2 vCPU
* 8GB RAM
* 100GB storage

Open Ports:

* `TCP 80` (HTTP)
* `TCP 443` (HTTPS) - only if provisioning SSL certificates


---

### DNS

Please create the following DNS `A` or `CNAME` entries and share with the Nanome team so we can configure your licenses.

If there's already an `A` record for the VM, please add `CNAME` records for the subdomains pointing to the VM's `A` record. Otherwise, create `A` records for the subdomains pointing to the VM's IP address.

If deploying with HTTPS, an SSL certificate will need to be generated covering \*.company.com, or each of the individual VM1 URLs below.

* `nanome.company.com` → VM1
* `nanome-tools.company.com` → VM1
* `workspaces.company.com` → VM1
* (optional) `nanome-auth.company.com` → VM1
  * (see “Auth Proxy” section)


---

### LLM

To access AI features in Nanome and the Web App, access to a LLM provider is needed. Currently the following are supported:

* Anthropic
* OpenAI
* AWS Bedrock
* Microsoft Foundry

For other provider support, please contact [support@nanome.ai](mailto:support@nanome.ai)

Before installation, acquire the URL and API Key or other auth details.

#### Anthropic

* Create API key
* See Embedding Model section of Installation

#### OpenAI

* Create API key

#### AWS Bedrock

* Create an IAM user with access to Bedrock
* Generate console access credentials (Access Key ID and Secret Access Key)

#### Microsoft Foundry

* Create API key or Service Principle
* Ensure the following models are deployed (or change accordingly during the deploy script)
  * `gpt-5.5` (if no quota, `gpt-5.4` is also acceptable)
  * `gpt-5.4-mini`
  * `gpt-realtime-whisper` (for voice commands)
  * `text-embedding-ada-002`


---

### Pre-Deploy checklist

* Nanome has provided AWS ECR Secret Access Tokens to customer
* Customer has set up LLM provider
* Customer has provisioned required VM and
  * Has shared URLs/IP to Nanome for license configuration
  * (optional) SSL certificate has been generated for VM1 services
* XR Headset properly setup and Nanome v2 is installed on device
  * Download from [nanome.ai/setup](https://nanome.ai/setup)
* Customer IT installation representative has confirmed both SSH access to VM1


---

## Installation

### Linux VM1


1. SSH into the Linux VM
2. Install `git` and `python` (install command depends on Linux Distribution)
3. ```javascript
   git clone https://github.com/nanome-ai/nanome-deployer.git
   cd nanome-deployer
   python install_prereqs.py
   ```
4. Restart VM for changes to take effect
5. Run `python setup.py` and follow prompts for setup
   * “What would you like to deploy?” - Select “Everything”
   * Domain name (from DNS for VM1, e.g. company.com)
   * Enable HTTPS? If yes:
     * SSL certificates will need to be placed on VM in a folder accessible to deployer script
   * Enable AI? If yes:
     * Select provider (Anthropic / OpenAI / AWS Bedrock / Microsoft Foundry)
     * Provider-specific settings:
       * AWS Bedrock
         * Region
         * AWS Access Key + Secret (**not** Nanome provided ones)
       * Microsoft Foundry
         * LLM API URL
         * LLM API Version (defaults to `2024-08-01-preview`)
         * Embedding API Version (defaults to `2023-05-15`)
         * Auth type: API Key or Service Principal
       * LLM model - Current recommendations:
         * `LLM_MODEL` = `gpt-5.5` / `claude-opus-4-7`
         * `LLM_MODEL_MD` = `gpt-5.4-mini` / `claude-sonnet-4-6`
         * `LLM_MODEL_SM` = `gpt-5.4-mini` / `claude-haiku-4-5`
       * Embedding Model
         * Anthropic: Anthropic does not host embedding models
           * Recommended to create API Key with Voyage AI ([voyageai.com](https://www.voyageai.com/))
           * Alternative: local embedding with HF-TEI (downside: heavy startup cost and 2GB RAM)
         * AWS Bedrock: recommended `cohere.embed-v4:0`
         * Microsoft Foundry / OpenAI: `text-embedding-ada-002`
6. Run `docker compose up -d --wait`
7. Verify URLs `nanome.company.com` and `workspaces.company.com` are accessible in browser


---

### Updating Existing Deployment

To update an existing on-prem deployment, ssh into the LInux VM and run the following

```javascript
cd nanome-deployer
python aws_login.py
docker compose up -d --wait
```


---

### Auth Proxy Server

A lightweight proxy service to route XR authentication and licensing requests to the Nanome API. Only useful if XR devices are isolated to internal network and prevent network egress to external network (e.g. to `api.nanome.ai`). The service is automatically started on VM1 during deployment, but XR devices need to be configured to use the proxy.

Setup using MDM

* Create plain text file named `nanome_config` containing

  ```javascript
  auth_proxy=http://nanome-auth.company.com
  ```
* Using MDM, add file to headset at path `/sdcard/Managed files/nanome_config`
* Open Nanome v2, a popup should show up saying unable to reach Nanome servers
* Click the button to enable local config access
* Accept the system prompt to allow file storage access
* Verify able to log in


---

## Testing

Test Nanome Web App

* Navigate to `nanome.company.com` and log in
* Drag and drop a molecular file (PDB) onto the page and create a workspace
* Ensure workspace contains molecule

Test Collaboration

* Open Nanome on XR headset and log in
* Verify workspace shows up and molecule visible
* While in XR, verify XR cursors appear in Web preview


---

## Troubleshooting

The following are errors that may be encountered during deployment or redeployment.

#### “Error response from daemon: pull access denied”

On a fresh deployment, this means the AWS access was not correctly configured. Verify the Access Key and Secret Key are present in `~/.aws/credentials`, then run `python aws_login.py` and try again.

For redeployment, just run the `python aws_login.py` command before `docker compose up -d --wait`

#### “chromadb.errors.InvalidDimensionException - Embedding dimension X does not match collection dimensionality Y

If a deployment is updated to use a different text embeddings models, this error will occur. The default model on older deployments is `text-embedding-ada-002`, so if it is updated to a different model, the old embeddings must be cleared:

```javascript
docker compose down
docker volume rm nanome-deployer_mara-embeddings-volume
docker compose up -d --wait
```