Skip to main content

Quick Start Guide

Deploy your first Alactic AGI instance in under 15 minutes with this step-by-step guide.

Overview​

This guide walks you through:

  1. Opening Azure Marketplace
  2. Configuring deployment parameters
  3. Starting the deployment
  4. Accessing your Alactic AGI instance
  5. Verifying everything works

Time Required: 10-15 minutes for deployment + 10-15 minutes for Azure resource provisioning

Step 1: Navigate to Azure Marketplace​

  1. Visit the Azure Marketplace
  2. Search for "Alactic AGI"
  3. Click on the Alactic AGI offering

Option B: From Azure Portal​

  1. Sign in to Azure Portal
  2. Click "+ Create a resource"
  3. Search for "Alactic AGI"
  4. Click the Alactic AGI result

Step 2: Configure Deployment​

Basics Tab​

Subscription

  • Select your Azure subscription from the dropdown
  • Ensure Azure OpenAI Service is approved for this subscription

Resource Group

  • Choose "Create new" and enter a name (e.g., alactic-agi-prod)
  • Or select an existing resource group
  • Best Practice: Use a dedicated resource group for easier management

Region

  • Select an Azure region close to your users
  • Verify the region supports Azure OpenAI Service
  • Recommended regions: East US, West Europe, UK South
  • See Regional Availability for full list

Plan Selection

  • Free: 50 URLs, 20 PDFs, gpt-4o-mini only
  • Pro: 200 URLs, 100 PDFs, gpt-4o and gpt-4o-mini
  • Pro+: 1000 URLs, 500 PDFs, gpt-4o and gpt-4o-mini
  • Enterprise: Unlimited, custom configuration

See Plan Comparison for detailed feature breakdown.

SSH Public Key Choose one of two options:

Option 1: Generate New Key (Recommended)

  • Select "Generate new key pair"
  • Enter a name (e.g., alactic-agi-key)
  • You'll download the private key after deployment

Option 2: Use Existing Key

  • Select "Use existing public key"
  • Paste your SSH public key
  • Format: ssh-rsa AAAAB3... user@host

Model Configuration Tab​

OpenAI Chat Model

  • Enter deployment name: alactic-gpt4o (or your preferred name)
  • Model: GPT-4o (Pro+ and Enterprise) or GPT-4o mini (Free and Pro)
  • This is created automatically during deployment

OpenAI Embedding Model

  • Enter deployment name: alactic-embedding
  • Model: text-embedding-3-large
  • Used for vector search functionality

Note: The deployment creates these models in Azure OpenAI Service automatically. You don't need to create them beforehand.

Review + Create​

  1. Review all configuration settings
  2. Check estimated monthly cost (shown at bottom)
  3. Read and accept terms and conditions
  4. Click "Create"

Download SSH Key: If you generated a new key pair, a download prompt appears immediately. Save this file securely - you cannot download it again.

Step 3: Monitor Deployment Progress​

Deployment Timeline​

  • Resource creation: 2-3 minutes
  • VM provisioning: 3-5 minutes
  • Software installation: 8-12 minutes
  • Total: 15-20 minutes

Tracking Progress​

  1. You'll see "Deployment in progress" page
  2. Click "Deployment details" to see individual resources
  3. Resources are created in this order:
    • Resource Group
    • Managed Identity
    • Key Vault
    • Cosmos DB
    • Azure OpenAI
    • Storage Account
    • Virtual Network
    • Network Security Group
    • Public IP Address
    • Network Interface
    • Virtual Machine
    • VM Extension (runs installation)

What's Happening​

While you wait, the deployment:

  1. Creates all Azure resources
  2. Configures networking and security
  3. Installs Ubuntu 22.04 on the VM
  4. Installs Python 3.11, Node.js 18, and dependencies
  5. Downloads and configures Alactic AGI application
  6. Sets up Nginx reverse proxy
  7. Starts backend and frontend services
  8. Configures systemd for automatic restart

Step 4: Access Your Instance​

Get Your Application URL​

Once deployment completes:

  1. Go to "Deployment outputs" tab
  2. Copy the applicationURL
  3. Format: http://your-vm-name.region.cloudapp.azure.com:3000

Get Your Deployment Access Key​

The deployment access key is required to use the application:

  1. Still in "Deployment outputs" tab
  2. Copy the deploymentAccessKey
  3. Format: ak-xxxxxxxxxxxxx (unique per deployment)

Important: This key cannot be changed or regenerated. Store it securely.

First Login​

  1. Open the applicationURL in your browser
  2. You'll see the Alactic AGI access gate
  3. Paste your deployment access key
  4. Click "Verify Access"
  5. The key is stored in your browser (localStorage)

Step 5: Verify Installation​

Test Document Upload​

  1. Click "Upload PDF" in the interface
  2. Select a PDF file (max 10MB for testing)
  3. Click "Extract Content"
  4. Wait for processing to complete
  5. Review extracted text and summary

Test URL Processing​

  1. Click "Process URLs" tab
  2. Enter a test URL (e.g., https://en.wikipedia.org/wiki/Artificial_intelligence)
  3. Click "Process"
  4. Wait for scraping to complete
  5. Review extracted content

Check Settings​

  1. Click the Settings icon (gear) in top right
  2. Verify your plan is shown correctly
  3. Verify deployment key is displayed
  4. Check model access matches your plan

Verify Services​

SSH into your VM to check services:

ssh -i path/to/your-key.pem appuser@your-vm-fqdn

# Check backend service
sudo systemctl status alactic-backend

# Check frontend service  
sudo systemctl status alactic-frontend

# Check nginx
sudo systemctl status nginx

All three should show "active (running)" status.

Troubleshooting Quick Start​

Deployment Fails During Provisioning​

Problem: Resource creation fails

Solution:

  1. Check selected region supports all services
  2. Verify Azure OpenAI access is approved
  3. Check subscription quotas for VM SKUs
  4. Review Activity Log in Azure Portal for specific error

Application URL Not Accessible​

Problem: Cannot reach application URL after deployment

Wait Time: Allow 15-20 minutes for full installation

Solution:

  1. Verify NSG allows port 3000
  2. Check VM is running in Azure Portal
  3. SSH to VM and check service status
  4. Review nginx logs: sudo journalctl -u nginx -n 50

Access Key Not Working​

Problem: Deployment key shows "Invalid key"

Cause: Key mismatch or backend not initialized

Solution:

  1. Verify you copied the exact key from deployment outputs
  2. Wait 2-3 minutes for backend to fully initialize
  3. Check backend logs: sudo journalctl -u alactic-api -n 50
  4. Verify .env file exists: ls -la /home/alacticadmin/Alactic-AGI/.env

Model Not Found Error​

Problem: "Model deployment not found" error when processing

Cause: Azure OpenAI deployments not ready

Solution:

  1. Go to Azure OpenAI resource in portal
  2. Check "Model deployments" section
  3. Verify both chat and embedding models exist
  4. Wait 5-10 minutes after deployment for models to activate
  5. Check model names match exactly (case-sensitive)

Upload Fails with Permission Error​

Problem: PDF upload shows permission denied

Cause: Directory ownership misconfigured

Solution: SSH to VM and run:

sudo chown -R alacticadmin:alacticadmin /home/alacticadmin/Alactic-AGI/uploads
sudo chmod 755 /home/alacticadmin/Alactic-AGI/uploads
sudo systemctl restart alactic-api

Common Post-Deployment Tasks​

Connecting from Multiple Devices​

The deployment key works from any browser or device. Simply enter it on the access gate page.

Monitoring Usage​

Track token usage in Azure OpenAI resource:

  1. Go to Azure OpenAI resource
  2. Click "Metrics"
  3. View "Processed Inference Tokens" metric

Setting Up Alerts​

Configure cost alerts to avoid unexpected charges:

  1. Go to "Cost Management + Billing"
  2. Create budget for resource group
  3. Set threshold alerts (e.g., 80%, 100% of budget)

Backup Configuration​

Important data to backup:

  • Deployment access key
  • SSH private key
  • Application URL
  • Azure OpenAI endpoint and keys (stored in Key Vault)

Next Steps​

Now that your instance is running:

Getting Help​

If you encounter issues: