Installation and Setup Guide
Overview
This guide walks you through deploying UnderstandTech on your brand new NVIDIA DGX Spark system.
What you'll have done
UnderstandTech accessible at https://understand.local from any device on your network
GPU-accelerated LLM inference running entirely on your hardware
A web-based management interface (see Portainer Guide) for monitoring and controlling services
Full administrative control over your deployment
All data stored locally on your DGX, never leaving your premises
Time Required: ~20 minutes (plus image download time)
Internet Connection Required: The initial setup requires an internet connection to download software components.
Setting up your DGX Spark
If this is a brand-new DGX Spark fresh out of the box, you'll need to complete NVIDIA's first-time setup before installing UnderstandTech. This section walks you through that process. If your DGX is already set up with a working desktop and network connection, skip ahead to Prerequisites.
For full details on the first-boot process, see NVIDIA's official documentation: https://docs.nvidia.com/dgx/dgx-spark/first-boot.html
What You'll Need
Your DGX Spark unit
A monitor connected to the DGX
A USB keyboard and mouse
A stable Wi-Fi network with internet access, or an Ethernet connection. Avoid captive-portal networks (hotels, airports) and phone hotspots — the setup process downloads a large software image and can't recover gracefully from dropped connections.
A separate device to run the NVIDIA Sync app later
Initial Boot and OS Setup
Important: The DGX Spark powers on automatically as soon as you plug it in. Connect your monitor, keyboard, and mouse before connecting the power cable.
Connect peripherals and apply power. Plug in the monitor, keyboard, and mouse first, then connect the power supply. The DGX will boot and launch NVIDIA's first-time setup wizard automatically.
Select your language, time zone, and keyboard layout. The wizard walks you through these one at a time. The input fields filter as you type, so you can start typing your time zone or language name to find it quickly.
Accept the terms and conditions. Review and accept NVIDIA's license terms to continue.
Create your user account. This is the most important step for the UnderstandTech deployment:
Username: Use ut
This username matters. The UnderstandTech deployment scripts, file paths, and service configurations all reference the ut account. Using a different username will require modifying multiple configuration files later.
Password: Choose a strong password you'll remember. You'll need it for sudo commands throughout this guide and for SSH access later.
Configure information sharing (optional). You can choose whether to share analytics and crash reporting data with NVIDIA. This is entirely optional.
Connect to your network. Select your Wi-Fi network and enter its password. If you've already connected an Ethernet cable, this step is skipped automatically.
Why Ethernet is better for this setup: The first-boot process downloads the full DGX software image, and the UnderstandTech installation that follows downloads several gigabytes of container images. Ethernet will make both of these steps significantly faster and more reliable.
Wait for the software download and installation to complete. After connecting to the network, the DGX downloads and installs its full software image. This is the longest part of the process and can take 10 minutes or more depending on your connection speed. The system may reboot more than once during this phase.
Do not shut down or unplug the DGX during this step. The installation cannot be interrupted once the download begins — powering down during updates can damage the system software and require a full recovery.
Log in. When installation is complete, the DGX reboots one final time and presents the login screen. Sign in with the ut account you just created. You should now be at the Ubuntu desktop the DGX is ready for the next phase.
Connect from Your Device with NVIDIA Sync
The NVIDIA Sync app lets you manage your DGX remotely - browsing files, opening a terminal, and monitoring system status without needing a monitor plugged into the DGX. While not strictly required for the UnderstandTech installation, it's useful for ongoing management and is worth setting up now.
Download the NVIDIA Sync app on your separate device (Windows/macOS). It's available from https://build.nvidia.com/spark/connect-to-your-spark/sync.
For more details on Sync's capabilities, see NVIDIA's documentation: https://docs.nvidia.com/dgx/dgx-spark/nvidia-sync.html
Open the app and select "Add New Device."
Enter the connection details:
Hostname: This is the same as the hotspot SSID printed on the Quick Start Guide that came in the DGX box. It typically looks something like spark-a2b4. Look on the card or sticker included with your DGX packaging.
Username: ut (the account you created during setup)
Password: The password you chose during setup
Connect. The app should find your DGX on the local network and establish a connection. If it can't find the device, make sure your laptop/phone is on the same Wi-Fi network as the DGX.
You're now ready to begin the UnderstandTech installation. You'll need a terminal (command line) for the remaining steps.
Open a Terminal
Right-click the desktop and select "Open Terminal," or press Ctrl+Alt+T. With a terminal open, continue to the Prerequisites section below.
Prerequisites
Hardware
NVIDIA DGX Spark with initial OS setup complete (see above)
Keyboard, monitor, and mouse connected to the DGX (for initial setup; remote management is possible afterward)
Network connection — the DGX should be connected to the same network as the devices you'll use to access UnderstandTech
Credentials from UnderstandTech
Before starting, make sure you've received the following from the UnderstandTech team:
Credential
Format
Purpose
Service account username
dgx-access
Authenticates with our container registry
Access token
Starts with ghp_...
Grants permission to download UnderstandTech software
Keep your token secure. This token is unique to your deployment. Do not share it, commit it to any repository, or include it in files that others can access. If you suspect it has been compromised, contact UnderstandTech immediately for a replacement.
If you haven't received these credentials, contact us at [email protected].
Setting up the UnderstandTech platform
Step 1: Verify Docker Is Installed
Docker is the platform that runs all UnderstandTech services as isolated containers. It should already be installed on your DGX Spark, but let's confirm. Open a terminal and run:
You should see output like Docker version 24.x.x or newer. If Docker is not installed, refer to your DGX system documentation or contact UnderstandTech support.
Step 2: Add Your User to the Docker Group
By default, Docker commands require sudo (administrator) privileges. Adding your user to the docker group lets you run Docker commands directly, which simplifies day-to-day management.
Enter your password when prompted. This change won't take effect until you log out and back in (or reboot, which we'll do shortly).
Step 3: Authenticate with GitHub Container Registry
UnderstandTech's software is distributed as container images hosted on GitHub's Container Registry (GHCR). You need to authenticate so your DGX can download these images.
Run the following command, then paste your access token when prompted for a password:
You should see Login Succeeded. If you see unauthorized or denied, double-check your token and try again. If the problem persists, your token may have expired — contact UnderstandTech for a replacement.
What's happening here: This stores an authentication credential on the DGX so that Docker can pull private images from ghcr.io/understand-tech/. The credential persists across reboots, so you only need to do this once (unless the token is revoked or replaced).
Step 4: Clone the Repository
The repository contains the configuration files that tell Docker how to assemble and run the UnderstandTech platform. Clone it to your home directory:
Enter.
Replace <YOUR_ACCESS_TOKEN> with the token provided by UnderstandTech (the same one you used in Step 3).
What this creates: A ~/understand-tech directory containing compose.yaml (the service definitions), Caddyfile (the web server configuration), environment templates, and operational scripts you'll use to manage the platform.
Step 5: Configure mDNS (Network Discovery)
mDNS (multicast DNS) allows devices on your local network to find the DGX using the friendly hostname understand.local instead of requiring you to remember an IP address. This step changes the DGX's hostname and installs the service that broadcasts it on the network.
First, note your current hostname — you'll need it in a moment:
Copy the output (e.g., spark-a2c4) and save it somewhere.
Now install/update the mDNS daemon and update the hostname:
Install the Avahi mDNS daemon
Change the system hostname to "understand"
Update the hosts file to match the new hostname
Important: In the sed command above, replace OLD_HOSTNAME with the hostname you copied earlier.
Restart the mDNS service
Why this matters: Without mDNS, you'd need to find and type the DGX's IP address every time you want to access UnderstandTech. With mDNS configured, any device on the same network can simply navigate to https://understand.local. This works on macOS, Windows 10+, and most Linux distributions out of the box.
Step 6: Reboot
Both the Docker group membership (Step 2) and the hostname change (Step 5) require a reboot to take effect:
After this step, the system reboots and applies the changes we made earlier (step 3 & step 5).
After the system comes back up, sign in again and open a terminal and verify both changes applied correctly:
This is how it should look like:
If docker doesn't appear in the groups output like below, repeat Step 2 and reboot again.
Step 7: Install Portainer (Container Management UI)
Portainer gives you a web-based dashboard for monitoring and managing all UnderstandTech services. While everything can be done from the command line, Portainer provides a visual interface that's especially useful for checking service health, viewing logs, and restarting individual containers. Refer to the Portainer guide for detailed usage instructions.
Once running, access Portainer at https://localhost:9443 from the DGX itself (by opening Firefox).
On first access:
Your browser will show a security warning about the self-signed certificate; this is expected and safe for internal use. Click "Advanced" → "Proceed" to continue.
Create an administrator account. Choose a strong password (minimum 12 characters) and save these credentials securely.
Select Get Started with Docker and click 'Live Connect'.
You can leave the webpage open for now.
What Portainer provides: A point-and-click interface for everything you'd otherwise do with docker commands like viewing container status, reading logs, restarting services, scaling workers, and more. See the Portainer Guide section later in this document for detailed usage instructions.
Step 8: Configure Environment Variables
The .env file contains all the configuration values that the UnderstandTech services need to run- database credentials, API keys, model settings, and more. This file is the single source of configuration for your entire deployment.
Open the terminal again, and navigate to the project directory and create your environment file from the provided template:
Open the file in VS Code (or any text editor) to configure it:
Understanding the .env File
The environment file is organized into three sections:
Section 1: Image Tags (Update for Releases)
These specify which versions of the UnderstandTech containers to run. When UnderstandTech releases an update, you'll receive new image tags to replace these values.
To update: Replace the tag portion (after the = symbol) with the new version provided by UnderstandTech, then run:
Before updating the tags, ensure that the platform is down (not active) by running:
Section 2: User Configuration (Edit These)
These are the values you should customize for your deployment:
MONGODB_USERNAME
Database administrator username
your_chosen_username
Change to your preferred username
MONGODB_PASSWORD
Database administrator password
<your_chosen_password>
Must change - use a strong password
WORKER_REPLICAS
Number of main API worker containers
2
Increase for higher throughput
WORKER_CUSTOMER_REPLICAS
Number of customer API worker containers
2
Increase for higher throughput
OLLAMA_MODEL_LLM
Base LLM model for UnderstandAI
gpt-oss:20b
See model options below
MongoDB Credentials
These credentials are set during first startup and used to access the database.
MONGODB_USERNAME= "your-chosen-username" (ex.: "admin") MONGODB_PASSWORD= "your-chosen-password" (ex. "password1234567")
Replace 'your-chosen-username' and 'your-chosen-password' with values you choose. These will be the administrator credentials for the MongoDB database that stores all application data.
Important constraints for MongoDB credentials:
Use only alphanumeric characters (letters and numbers). Special characters like @, #, !, or % can cause connection failures because they have special meaning in database connection strings.
Choose a strong password with at least 12 characters mixing uppercase, lowercase, and numbers.
These credentials are set during first startup. If you need to change them later, the process is more involved (see the MongoDB Guide section).
Worker Replicas
Workers process background jobs like document parsing, assistant generation, and async tasks. More workers = more parallel processing capacity.
Default (2): Suitable for small teams or testing
Production (4-8): Recommended for active usage
High volume (8+): For large deployments with many concurrent users
LLM Model Selection
The OLLAMA_MODEL_LLM setting determines which AI model powers UnderstandAI's responses.
gpt-oss:20b
Default model, good balance of quality and speed
~24GB
llama3:8b
Smaller, faster responses
~8GB
llama3:70b
Larger, higher quality responses
~48GB
qwen3:32b
Alternative large model
~32GB
Contact UnderstandTech for recommendations based on your hardware and use case.
Section 3: System Configuration (Do Not Edit)
These values are pre-configured to work with the Docker Compose setup. Changing them may break connectivity between services.
This section includes:
Internal service hostnames and ports
Embedding and reranker model paths
Authentication URLs and redirects
Storage and logging configuration
After configuring section 2, save the file (Ctrl + S), and close the editor.
Step 9: Deploy the Stack
You're now ready to pull the container images and start all services. This is where everything comes together.
What does the 1. step (pull) do? It downloads all the software components. This is the longest part of setup as the images include the application code, AI models, and their dependencies. Subsequent updates will be much faster as Docker only downloads what has changed.
What does the 2. step start? This command launches the entire platform - the web frontend, backend API, GPU-accelerated LLM service, MongoDB database, Redis cache, background workers, and the Caddy reverse proxy that ties them all together behind https://understand.local.
Step 10: Verify the Deployment
Services take a couple of minutes to initialize, especially the LLM service which needs to load AI models into GPU memory.
There are two ways to verify the deployment; through the terminal or via portainer.
Terminal:
Portainer: Open the portainer webpage, go to the sidebar, and click on 'Containers'. For more information check out the Portainer guide.
What "healthy" means: Each service has a built-in health check that periodically verifies it's working correctly. "Healthy" means the service is fully operational and ready to handle requests. If a service stays "unhealthy" for more than a few minutes, check its logs for errors. Learn where to check for logs from the Portainer guide.
Step 11: Setup the TLS Certificate for the Frontend
Once all the services are healthy and you first visit https://understand.local. Your browser will show a security warning, something like "Your connection is not private" (Chrome), "Warning: Potential Security Risk Ahead" (Firefox), or "This Connection Is Not Private" (Safari).
Why this happens: Caddy, the reverse proxy that sits in front of UnderstandTech, automatically generates an SSL certificate to encrypt all traffic between your browser and the DGX. This is a real, working certificate, and your connection is genuinely encrypted. However, because Caddy generated and signed this certificate itself (rather than a public authority like Let's Encrypt), your browser doesn't recognize the signer and flags it as untrusted. This is perfectly normal and expected for any locally-hosted service.
The quick workaround is to click through the warning each time: "Advanced" → "Proceed to understand.local." This works, but you and every user on your network will see the warning on every new browser session, which gets annoying and can cause confusion.
The proper fix is to export Caddy's root certificate and install it as a trusted certificate on each device that accesses UnderstandTech. Once installed, the warnings disappear permanently and the browser shows a normal padlock icon.
Export the Certificate from the DGX
On the DGX, run this command to extract the root CA certificate that Caddy uses to sign its SSL certificates:
This creates a file called caddy-root-ca.crt in your current directory. Important: You'll need to transfer this file to each device that should trust the certificate. You can do this via USB drive, email, shared network folder, or any encrypted messaging service. Follow the steps below for macOS, Windows and Linux machines:
Install on macOS
Double-click the caddy-root-ca.crt file. This opens Keychain Access automatically.
The certificate will appear in your login keychain. Find it in the list (it will be named something like "Caddy Local Authority").
Double-click the certificate to open its details.
Expand the Trust section.
Change "When using this certificate" to Always Trust.
Close the window. You'll be prompted for your macOS password to confirm the change.
Restart your browser. The warning should no longer appear when visiting https://understand.local.
Install on Windows
Double-click the caddy-root-ca.crt file. A certificate dialog will appear.
Click Install Certificate.
Select Local Machine (this trusts the certificate for all users on this Windows PC). Click Next.
Select Place all certificates in the following store, then click Browse.
Choose Trusted Root Certification Authorities. Click OK, then Next, then Finish.
If prompted by a security warning asking whether you want to install this certificate, click Yes.
Restart your browser. The warning should no longer appear.
Note for Windows users: If "Local Machine" is grayed out, you may need to run the certificate import as Administrator. Right-click the .crt file → "Install Certificate" and select "Local Machine" with elevated privileges.
Install on Linux
Most Linux browsers (Firefox, Chrome, Chromium) will pick up the system certificate after restart. Firefox uses its own certificate store, so if the warning persists in Firefox specifically, you can import the certificate manually: Settings → Privacy & Security → Certificates → View Certificates → Authorities → Import.
Enterprise Environments (MDM / Group Policy)
If your organization manages devices through a Mobile Device Management (MDM) platform or Active Directory Group Policy, you can distribute the Caddy root certificate across all managed devices at once.
In corporate environments, users may not have permission to install certificates themselves, and browser security warnings can trigger IT security alerts or helpdesk tickets. Deploying the certificate through your existing MDM or GPO infrastructure ensures a seamless experience for all users.
First-time Admin Configuration
When you first navigate to https://understand.local from any device on the same network as the DGX, you'll land on the Admin Configuration page (see below). This is a one-time setup wizard that configures the core of your UnderstandTech deployment. You'll see three sections:
LLM selection (optional)
single sign-on (SSO) (mandatory), and
data source integrations, (optional)
and then set an admin password to protect this configuration page going forward.
You must complete at least the SSO section to use the platform, since UnderstandTech requires SSO for user authentication. The LLM and data source sections can be revisited later from the admin panel.
Section 1: Choose Your LLMs
This section controls which AI models are available to your users inside the UnderstandTech "Assistants" apps.
Understand AI (the built-in AI assistant)
At the top, you'll see Understand AI. This is UnderstandTech's own AI assistant, which runs locally on your DGX's GPU. It's enabled by default and is the primary reason for having a DGX in the first place: all inference happens on your hardware, so your data never leaves your premises.
By default, Understand AI runs on the open-source gpt-oss:20b LLM. To learn how to customize the base LLM, head to Step 8.
Third-Party LLM Providers
Below Understand AI, you'll see a list of external LLM providers: OpenAI, Mistral, Anthropic Claude, Google Gemini, DeepSeek, xAI Grok, and Perplexity.
Enabling any of these gives your users the option to use that provider's model alongside (or instead of) the local Understand AI model. This is useful when you want to give users access to a broader range of models for different tasks, for example, using GPT-5 for complex reasoning or Perplexity for research with web sources.
The specific models that'll be available in the platform (GPT-5, Claude Sonnet 4.6, etc) are automatically added based on the configuration of the API keys you insert.
To enable a provider:
Check the box next to the provider name.
An API Key field will appear below it. Enter the API key you've obtained from that provider. Ensure that the specific model you want is available through that key.
Repeat for any additional providers you want to enable.
To disable a provider: Simply leave it unchecked.
Important: Enabling third-party providers means that queries sent to those models will leave your DGX and travel to the provider's servers over the internet. If data sovereignty is a concern, you may want to leave all third-party providers disabled and rely exclusively on Understand AI, which processes everything locally.
Section 2: Configure Single Sign-On (SSO)
This section is required. UnderstandTech uses OpenID Connect (OIDC) for all user authentication, so the platform won't be usable until SSO is configured. There is no built-in username/password login; all users sign in through your organization's identity provider (IdP).
You'll need the following values from your identity provider (e.g., Microsoft Entra ID, Okta, Google Workspace, Auth0, Keycloak, or any OIDC-compliant provider):
Field
What It Is
Where to Find It
Open ID Client ID
The application/client ID assigned to UnderstandTech in your IdP
Your IdP's app registration page
Open ID Client Secret
The secret used to authenticate the application with your IdP
Generated during app registration
Open ID Secret Key
A key used to sign and verify session tokens
Choose a long random string (32+ characters)
Open ID Redirect URI
Where the IdP sends users after login
Use https://understand.local/en/login/openid-auth
Open ID Server Metadata URL
The IdP's .well-known/openid-configuration endpoint
Your IdP's documentation (see examples below)
Open ID Token Endpoint URL
The endpoint that exchanges authorization codes for tokens
Found in the metadata URL response
Open ID JWKS Endpoint URL
The endpoint serving the public keys used to verify tokens
Found in the metadata URL response
Issuer
The issuer identifier for your IdP
Found in the metadata URL response
Common metadata URLs by provider:
Microsoft Entra ID: https://login.microsoftonline.com/{tenant-id}/v2.0/.well-known/openid-configuration
Okta: https://{your-domain}.okta.com/.well-known/openid-configuration
Google Workspace: https://accounts.google.com/.well-known/openid-configuration
Keycloak: https://{your-host}/realms/{realm}/.well-known/openid-configuration
Auth0: https://{your-domain}.auth0.com/.well-known/openid-configuration
Tip: If your IdP supports a discovery/metadata URL, start there. Navigating to the metadata URL in your browser will return a JSON document that contains the token endpoint, JWKS endpoint, and issuer values - you can copy them directly into the corresponding fields.
Need help? SSO configuration depends on your specific identity provider, and your IT or security team will likely need to register UnderstandTech as an application in your IdP. If you're unsure about any of these values, involve your identity/SSO administrator or contact UnderstandTech support.
API Keys Configuration
The application uses Sendgrid API to send emails to users regarding authentication, team invitations, workflow status, etc. Thus, configuring this key is required during first-time setup. To get started, create an account at sendgrid.com, and follow the steps outlined at https://www.twilio.com/docs/sendgrid/ui/account-and-settings/api-keys Once configured, enter it in the admin page and move to the next section.
Section 3: Data Source Integrations (Optional)
This section lets you connect UnderstandTech to external data sources so users can query and analyze data from tools they already use.
All integrations are optional. You can skip this entirely and configure them later from the admin panel.
Currently supported integrations:
Microsoft: Connects to OneDrive and SharePoint, allowing users to bring documents and files from their Microsoft 365 environment into UnderstandTech for AI-powered analysis.
HubSpot: Connects to your HubSpot CRM data.
Zoho: Connects to your Zoho CRM data.
To configure an integration, click the arrow (▶) next to the provider name to expand its settings panel. Each integration requires OAuth credentials from the respective provider.
Microsoft (OneDrive & SharePoint)
The Microsoft integration connects UnderstandTech to your organization's OneDrive and SharePoint, allowing users to bring documents and files from their Microsoft 365 environment into the platform for AI-powered analysis.
You'll need to register UnderstandTech as an application in Azure AD / Microsoft Entra ID. The fields map to values from that app registration:
Microsoft Client ID
The application (client) ID from your Entra ID app registration
Microsoft Client Secret
The secret generated for that app registration
Microsoft Redirect URI
The callback URL - use https://understand.local/api/microsoft/callback
Microsoft Authority
Your tenant's authority URL, typically https://login.microsoftonline.com/{tenant-id}
HubSpot
The HubSpot integration connects UnderstandTech to your HubSpot CRM, giving users the ability to query and analyze CRM data through the AI assistant.
You'll need to create a private app in your HubSpot account (Settings → Integrations → Private Apps). The fields map to values from that app:
HubSpot Client ID
The client ID from your HubSpot private app
HubSpot Client Secret
The client secret from your HubSpot private app
HubSpot App ID
The app ID assigned to your private app
HubSpot Redirect URI
The callback URL - use https://understand.local/api/hubspot/callback
Zoho
The Zoho integration connects UnderstandTech to your Zoho CRM, enabling users to access and analyze CRM data within the platform.
You'll need to register UnderstandTech as a client in the Zoho API Console (https://api-console.zoho.com/). The fields map to values from that registration:
Zoho Client ID
The client ID from the Zoho API Console
Zoho Client Secret
The client secret from the Zoho API Console
Zoho Auth URL
The Zoho authorization endpoint, typically https://accounts.zoho.com/oauth/v2/auth (use zoho.eu for EU data centers)
Zoho Token URL
The Zoho token endpoint, typically https://accounts.zoho.com/oauth/v2/token
Zoho Redirect URI
The callback URL — use https://understand.local/api/zoho/callback
Set Admin Password
This password protects access to the configuration page you just completed. Anyone who wants to change LLM settings, SSO configuration, or data source integrations in the future will need this password. Once set, click Save.
Choose a strong password (at least 12 characters) and store it securely. This is separate from your DGX system password and your SSO credentials.
Restarting API service
After clicking Save you will be redirected to the platform login page. However, to fully apply your saved configuration, the API service (ut-api) needs to be restarted. This is because sensitive credentials like API keys are initialized once only at the application startup. To restart the API service, open Portainer and head to the Containers tab. Find the API service in the list (ut-api), and select it (using the checkbox). Then, click on the Restart button at the top of the page.
It typically takes 5-15 seconds for the API container to fully restart. You can check its live status by refreshing the page periodically (by clicking the Refresh button next to the Container list heading).
Once the status returns to healthy, you're ready to go. Head to the login page (understand.local) and sign-in with your SSO provider.
The admin configuration page remains accessible at https://understand.local/en/workspace/admin using the password you just set.
And you’re all set! Welcome to Understand Tech 😄
Troubleshooting
"understand.local" Not Resolving
From another device on your network, open the terminal and run:
If not resolving:
Note: mDNS requires devices to be on the same network segment. Corporate networks with client isolation may block mDNS. Check with your network administrator.
Docker Permission Denied
GHCR Authentication Failed
If you see unauthorized or denied, contact UnderstandTech - your token may have expired or been revoked.
GPU Not Available
Firewall (if enabled)
Support
If you encounter issues not covered in this guide, contact us at [email protected].
Last updated