Installing LIT Platform#

This guide will help you install and run the LIT Platform using Docker. The installation is designed to work with your existing Ollama installation and is the recommended method for deploying LIT Platform in any environment.

Prerequisites#

Before you begin, make sure you have:

NVIDIA GPU with compatible drivers installed
- The LIT Platform requires NVIDIA GPU support for optimal performance
- Run nvidia-smi to confirm your GPU drivers are properly installed
CUDA Toolkit installed on your system
- Required for GPU acceleration
- Recommended version: CUDA 11.8 or later
- Verify installation with nvcc --version
NVIDIA Container Toolkit installed and configured
- Required for Docker containers to access the GPU
- Install with: sudo apt-get install nvidia-container-toolkit
- Configure with: sudo nvidia-ctk runtime configure --runtime=docker
- Restart Docker: sudo systemctl restart docker
Docker and Docker Compose installed on your system
- Docker installation guide
- Docker Compose installation guide
- Verify Docker can access your GPU with: docker run --rm --gpus all nvidia/cuda:11.8.0-base-ubuntu22.04 nvidia-smi
Ollama running on your network
- If you haven't installed Ollama yet, follow the Ollama installation guide
- Verify Ollama is running: curl http://localhost:11434/api/tags
Data Directory created with appropriate permissions
- Create with: sudo mkdir -p /data && sudo chmod 777 /data
- This directory will store all models, datasets, and artifacts
Your host IP address (the IP address of the machine where you're installing LIT)
- You can find this by running hostname -I on Linux or by checking your network settings

Installation Steps#

1. Create a Directory for LIT Platform#

mkdir -p ~/lit-platform
cd ~/lit-platform

2. Download Required Configuration Files#

# Download docker-compose.yml
curl -sSL -o docker-compose.yml https://lit-install.s3.us-east-2.amazonaws.com/docker-compose.yml

# Download Keycloak realm configuration
curl -sSL -o realm-export.json https://lit-install.s3.us-east-2.amazonaws.com/realm-export.json

3. Create an Environment File#

Create a file named .env in the lit-platform directory with the following content:

echo "HOST_IPS=YOUR_HOST_IP_ADDRESS" > .env
echo "OLLAMA_HOST=http://YOUR_HOST_IP_ADDRESS:11434" >> .env

Replace YOUR_HOST_IP_ADDRESS with your actual host IP address. For example:

echo "HOST_IPS=192.168.86.118" > .env
echo "OLLAMA_HOST=http://192.168.86.118:11434" >> .env

!!! note Make sure your Ollama instance is running at the specified address and port.

!!! warning "Important: IP Address Selection" During first-time initialization, you will be prompted to bind to an IP address. You must select an IP address that is accessible to both:

1. Your browser on your host machine
2. The Docker containers in the lit-platform network

**Recommended options:**
- Use your machine's LAN IP address (e.g., 192.168.x.x) if you need to access the platform from other machines on your network
- Use `localhost` or `127.0.0.1` only if you're accessing the platform exclusively from the same machine
- Avoid using Docker-specific addresses (like `172.17.0.1`) that may not be reachable from outside the Docker network

**Potential issues if you choose incorrectly:**
- Keycloak authentication may fail
- API requests from the frontend may not reach the backend
- You may be able to see the login page but not be able to authenticate properly

If you encounter connectivity issues after installation, you may need to reset and reinstall the platform with a more appropriate IP address.

4. Security Configuration (IMPORTANT)#

Before deploying the LIT Platform, it's crucial to set secure passwords in your configuration:

Open your docker-compose.yml file and update the following default passwords:
KEYCLOAK_ADMIN_PASSWORD: The admin password for Keycloak
POSTGRES_PASSWORD and related database passwords
KEYCLOAK_SECRET: The client secret for API authentication

# Example of password locations to change in docker-compose.yml
services:
  lit-app:
    environment:
      KEYCLOAK_DB_PASSWORD: "your_secure_db_password"  # Change this
      KEYCLOAK_ADMIN_PASSWORD: "your_secure_admin_password"  # Change this
      KEYCLOAK_SECRET: "your_secure_client_secret"  # Change this

  keycloak:
    environment:
      KC_DB_PASSWORD: "your_secure_db_password"  # Change this (same as above)
      KEYCLOAK_ADMIN_PASSWORD: "your_secure_admin_password"  # Change this (same as above)

  keycloak-db:
    environment:
      POSTGRES_PASSWORD: "your_secure_db_password"  # Change this (same as above)

!!! danger "Security Risk" Using default passwords poses a significant security risk. Always replace them with strong, unique passwords before deploying in any environment.

5. Pull and Start the Docker Containers#

docker compose up -d

This command will: - Pull the necessary Docker images from our repository - Create and start the containers defined in the docker-compose.yml file - Run the containers in the background (-d flag)

The initial pull might take some time depending on your internet connection speed.

6. Configure Keycloak and Create a User#

Before you can use the LIT Platform, you need to create a user in Keycloak:

Access the Keycloak administration interface:
```
http://localhost:8080
```
Log in with the administrator credentials:
Username: admin
Password: The value you set for KEYCLOAK_ADMIN_PASSWORD in your docker-compose.yml

!!! important "Realm Distinction" Keycloak uses the concept of "realms" to create isolated environments. When you first log in, you'll be in the Master realm, which is only for Keycloak administration. User accounts in the Master realm (including the admin account) cannot be used to log into the LIT application.

Navigate to the LIT realm:
- In the top-left dropdown, select "LIT"
- This realm is specifically configured for the LIT application
- All user accounts for accessing the LIT application must be created in this realm
Create a new user:
- Click on "Users" in the left sidebar
- Click "Add user" button
- Fill in the following details: - Username: (choose a username) - Email: (optional) - First Name: (optional) - Last Name: (optional)
- Click "Create"

!!! recommendation It's recommended to create at least one user named 'admin' in the LIT realm. This user will have special privileges within the LIT application and can access all files in the data directory.

Set a password for the user:
- After creating the user, go to the "Credentials" tab
- Click "Set password"
- Enter and confirm the password
- Uncheck "Temporary" if you don't want to force a password change on first login
- Click "Save"
- Confirm by clicking "Set password" in the dialog

Understanding Keycloak Realms in LIT Platform#

The LIT Platform uses two separate Keycloak realms:

Master Realm: This is the default Keycloak administrative realm.
- Used only for managing Keycloak itself
- The admin user credentials you set in your docker-compose.yml are for this realm
- Users in this realm cannot log into the LIT application
LIT Realm: This is the application-specific realm for LIT Platform.
- All user accounts for accessing the LIT application must be created here
- The LIT application is configured to only authenticate against this realm
- A user named 'admin' in this realm will have special privileges in the application

!!! important If you ever need to change the Master realm admin password, you must update it in both the KEYCLOAK_ADMIN_PASSWORD environment variable in the docker-compose.yml file and through the Keycloak admin interface.

7. Access the LIT Platform#

Once you've created a user, you can access the LIT Platform at:

http://localhost

Log in with the user credentials you created in the LIT realm (not the Master realm admin account).

!!! warning "Authentication Error" If you try to log in using the Master realm admin credentials, authentication will fail. You must use credentials for a user account created in the LIT realm as described in the previous section.

!!! note "Startup Time" After running docker compose up -d, it may take up to 10 seconds for Keycloak to fully initialize before the authentication system is ready. If you encounter authentication issues immediately after startup, please wait a moment and try again.

Verifying the Installation#

To ensure all components are working correctly:

Check NVIDIA GPU Access:
- From inside the container: docker exec -it lit-app nvidia-smi
- This should display your GPU information and confirm the container can access it
Verify Ollama Connection:
- Access the LIT Platform and navigate to the Chat widget
- The platform should be able to list available models from your Ollama instance
- Try sending a message to confirm the integration is working
Test Data Directory Access:
- Create a file in the platform (e.g., upload a dataset)
- Verify it appears in your host's /data directory with proper permissions

Troubleshooting#

Checking Container Status#

If you're experiencing issues, check if all containers are running properly:

docker compose ps

Viewing Container Logs#

To view the logs of the containers:

docker compose logs

For logs of a specific service:

docker compose logs lit-app

Add the -f flag to follow the logs in real-time:

docker compose logs -f lit-app

Common Issues#

NVIDIA GPU Not Detected
- Verify NVIDIA drivers are installed: nvidia-smi
- Check NVIDIA Container Toolkit: sudo nvidia-container-cli info
- Ensure Docker is configured for GPU support: docker info | grep -i nvidia
Cannot connect to Ollama
- Make sure Ollama is running: curl http://localhost:11434/api/tags
- Check if there are firewall rules blocking the connection
- Verify the OLLAMA_HOST in your .env file matches the actual location
Data Directory Issues
- Ensure /data exists and has proper permissions: ls -la /data
- Check if the container can write to it: docker exec -it lit-app touch /data/test.txt
- Verify user permissions match between host and container
Port conflicts
- If ports 80, 5000, or 8080 are already in use, modify the port mappings in the docker-compose.yml file
Authentication or database issues
- If you changed passwords in docker-compose.yml after an initial setup, ensure they are consistent across all related environment variables
- If you're connecting to an existing Keycloak database with a new password, you may need to update the database credentials in Keycloak as well

Initialization Issues#

If the platform gets stuck during initialization:

Delete the initialization file:

docker exec -it lit-app rm /etc/lit/initialized.txt

Restart the containers:
```
docker compose restart
```

Updating LIT Platform#

When a new version is available, you can update by pulling the latest image and restarting the containers:

docker compose pull
docker compose up -d

Stopping and Removing#

To stop the containers while preserving data:

docker compose down

To stop the containers and remove all data:

docker compose down -v

Data Storage#

By default, the LIT Platform stores all data in the /data directory, which is mapped directly to the /data directory on your host machine. This allows you to easily access and manage data files directly from your host system.

Default Configuration#

With the default configuration, all models, datasets, and other artifacts are stored in the host's /data directory:

volumes:
  - /data:/data

This means: - You need to ensure the /data directory exists on your host machine - The directory should have appropriate permissions (e.g., sudo mkdir -p /data && sudo chmod 777 /data) - All files created by the application will be accessible directly from your host at /data

User Permissions and Mapping#

The LIT Platform implements a secure permission model that maps Keycloak users to local Linux users to ensure proper file ownership and access control in the /data directory.

How User Mapping Works#

Admin User: When logged in as the 'admin' user in Keycloak, commands execute as the container's root user, allowing full access to all files and directories.
Standard Users: When logged in as any other user in Keycloak, the platform uses gosu to execute commands as the corresponding local Linux user, ensuring:
- Files created by the user are owned by that user
- Access control follows standard Linux permissions
- Users cannot access files owned by other users unless permissions allow

This approach maintains proper security boundaries between users and ensures data isolation.

Setting Up User Mapping#

For proper permission handling, you should create Keycloak users that match your existing local Linux users:

Use Existing Local Users:

# List existing Linux users that should have access to the platform
cat /etc/passwd | grep "/home" | cut -d: -f1

# Ensure their data directories exist
sudo mkdir -p /data/username

# Set correct ownership
sudo chown username:username /data/username

Create Matching Keycloak Users: When creating users in Keycloak, use usernames that exactly match your local Linux usernames.

Directory Structure: Maintain a consistent directory structure:

/data/
├── user1/             # Owned by user1, accessible only by user1 and root
├── user2/             # Owned by user2, accessible only by user2 and root
└── shared/            # Shared directory with appropriate group permissions

Admin-Only Setup#

If you prefer simplicity and don't need multi-user isolation, you can use just the 'admin' account:

Admin Account Benefits:
- All operations run as the container's root user
- No need to set up user mapping
- Full access to all files in the /data directory
- Simplified permission management
Using Admin Account Only:
- During Keycloak setup, only create and use the default 'admin' user
- All files created through the platform will be owned by root
- No additional Linux user configuration is required
Considerations:
- Files created in /data will be owned by root, which may require elevated privileges when accessing from the host
- This approach works well for single-user deployments or when all users share access to everything
- Not recommended for environments where data isolation between users is required

For many deployments, especially personal or small team installations, the admin-only approach provides the simplest experience while still maintaining the security of the platform itself.

Need Help?#

If you encounter any issues not covered in this guide, please contact our support team at support@lit.ai.