botbook/src/01-introduction/local-domains.md

Configuring Local Development Access

After bootstrap, BotServer services are immediately accessible via IP addresses - no configuration required. For those who prefer friendly hostnames, optional DNS setup is also available.

Zero Configuration: IP Access (Default)

BotServer certificates include 127.0.0.1 as a Subject Alternative Name (SAN), so mTLS works immediately via IP address without any system changes.

Service Ports

Component	Description	IP:Port
api	Main BotServer API	127.0.0.1:8443 (HTTPS) / 127.0.0.1:8080 (HTTP)
tables	PostgreSQL database	127.0.0.1:5432
drive	Object storage (S3-compatible)	127.0.0.1:9000
cache	Redis cache	127.0.0.1:6379
vectordb	Vector database	127.0.0.1:6333
vault	Secrets management	127.0.0.1:8200
llm	Local LLM server	127.0.0.1:8081
embedding	Embedding server	127.0.0.1:8082
directory	Authentication/Identity	127.0.0.1:8085
email	Email server	127.0.0.1:25 (SMTP) / 127.0.0.1:993 (IMAP)
meet	Video conferencing	127.0.0.1:7880

Quick Test

# Test API (no config needed)
curl -k https://127.0.0.1:8443/health

# With mTLS client certificate
curl --cert ./botserver-stack/conf/system/certificates/api/client.crt \
     --key ./botserver-stack/conf/system/certificates/api/client.key \
     --cacert ./botserver-stack/conf/system/certificates/ca/ca.crt \
     https://127.0.0.1:8443/api/v1/status

Code Examples

Python

import requests

response = requests.get(
    "https://127.0.0.1:8443/api/v1/bots",
    cert=("./botserver-stack/conf/system/certificates/api/client.crt",
          "./botserver-stack/conf/system/certificates/api/client.key"),
    verify="./botserver-stack/conf/system/certificates/ca/ca.crt"
)
print(response.json())

Node.js

const https = require('https');
const fs = require('fs');

const options = {
  hostname: '127.0.0.1',
  port: 8443,
  path: '/api/v1/bots',
  method: 'GET',
  cert: fs.readFileSync('./botserver-stack/conf/system/certificates/api/client.crt'),
  key: fs.readFileSync('./botserver-stack/conf/system/certificates/api/client.key'),
  ca: fs.readFileSync('./botserver-stack/conf/system/certificates/ca/ca.crt')
};

https.request(options, (res) => {
  res.on('data', (d) => process.stdout.write(d));
}).end();

Rust

use reqwest::Certificate;
use std::fs;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let cert = fs::read("./botserver-stack/conf/system/certificates/api/client.crt")?;
    let key = fs::read("./botserver-stack/conf/system/certificates/api/client.key")?;
    let ca = fs::read("./botserver-stack/conf/system/certificates/ca/ca.crt")?;
    
    let identity = reqwest::Identity::from_pem(&[cert, key].concat())?;
    let ca_cert = Certificate::from_pem(&ca)?;
    
    let client = reqwest::Client::builder()
        .identity(identity)
        .add_root_certificate(ca_cert)
        .build()?;
    
    let response = client
        .get("https://127.0.0.1:8443/api/v1/bots")
        .send()
        .await?;
    
    println!("{}", response.text().await?);
    Ok(())
}

Remote Server Access

If BotServer runs on a different machine (e.g., 192.168.1.100), regenerate certificates with additional IP SANs:

./botserver regenerate-certs --san-ip 192.168.1.100 --san-ip 10.0.0.50

Or configure before bootstrap in botserver-stack/conf/system/ca-config.toml:

[certificates.api]
san_names = ["localhost", "api.botserver.local", "127.0.0.1", "192.168.1.100"]

---

Optional: Hostname Access

For browser access with friendly URLs, configure your system to resolve *.botserver.local hostnames.

Hostname Mapping

Component	Hostname
api	api.botserver.local
tables	tables.botserver.local
drive	drive.botserver.local
cache	cache.botserver.local
vectordb	vectordb.botserver.local
vault	vault.botserver.local
llm	llm.botserver.local
embedding	embedding.botserver.local
directory	directory.botserver.local
email	email.botserver.local
meet	meet.botserver.local

Option 1: Edit hosts file (Simplest)

Windows

Open Notepad as Administrator, edit C:\Windows\System32\drivers\etc\hosts:

127.0.0.1 botserver.local
127.0.0.1 api.botserver.local
127.0.0.1 tables.botserver.local
127.0.0.1 drive.botserver.local
127.0.0.1 cache.botserver.local
127.0.0.1 vectordb.botserver.local
127.0.0.1 vault.botserver.local
127.0.0.1 llm.botserver.local
127.0.0.1 embedding.botserver.local
127.0.0.1 directory.botserver.local
127.0.0.1 email.botserver.local
127.0.0.1 meet.botserver.local

PowerShell one-liner (run as Administrator):

@"
127.0.0.1 botserver.local
127.0.0.1 api.botserver.local
127.0.0.1 tables.botserver.local
127.0.0.1 drive.botserver.local
127.0.0.1 cache.botserver.local
127.0.0.1 vectordb.botserver.local
127.0.0.1 vault.botserver.local
127.0.0.1 llm.botserver.local
127.0.0.1 embedding.botserver.local
127.0.0.1 directory.botserver.local
127.0.0.1 email.botserver.local
127.0.0.1 meet.botserver.local
"@ | Add-Content C:\Windows\System32\drivers\etc\hosts

Linux

sudo tee -a /etc/hosts << 'EOF'
127.0.0.1 botserver.local
127.0.0.1 api.botserver.local
127.0.0.1 tables.botserver.local
127.0.0.1 drive.botserver.local
127.0.0.1 cache.botserver.local
127.0.0.1 vectordb.botserver.local
127.0.0.1 vault.botserver.local
127.0.0.1 llm.botserver.local
127.0.0.1 embedding.botserver.local
127.0.0.1 directory.botserver.local
127.0.0.1 email.botserver.local
127.0.0.1 meet.botserver.local
EOF

macOS

sudo tee -a /etc/hosts << 'EOF'
127.0.0.1 botserver.local
127.0.0.1 api.botserver.local
127.0.0.1 tables.botserver.local
127.0.0.1 drive.botserver.local
127.0.0.1 cache.botserver.local
127.0.0.1 vectordb.botserver.local
127.0.0.1 vault.botserver.local
127.0.0.1 llm.botserver.local
127.0.0.1 embedding.botserver.local
127.0.0.1 directory.botserver.local
127.0.0.1 email.botserver.local
127.0.0.1 meet.botserver.local
EOF

# Flush DNS cache
sudo dscacheutil -flushcache
sudo killall -HUP mDNSResponder

Option 2: Use BotServer's CoreDNS

BotServer runs CoreDNS on port 53. Point your system to use it as DNS server.

Windows

# Get active interface
$interface = (Get-NetAdapter | Where-Object {$_.Status -eq "Up"}).Name

# Set DNS servers
Set-DnsClientServerAddress -InterfaceAlias $interface -ServerAddresses ("127.0.0.1","8.8.8.8")

Linux (systemd-resolved)

sudo mkdir -p /etc/systemd/resolved.conf.d/
sudo tee /etc/systemd/resolved.conf.d/botserver.conf << 'EOF'
[Resolve]
DNS=127.0.0.1
FallbackDNS=8.8.8.8 8.8.4.4
Domains=~botserver.local
EOF
sudo systemctl restart systemd-resolved

macOS

sudo mkdir -p /etc/resolver
sudo tee /etc/resolver/botserver.local << 'EOF'
nameserver 127.0.0.1
EOF

This routes only *.botserver.local queries to BotServer's DNS.

---

Trusting Self-Signed Certificates

For browser access without warnings, trust the CA certificate:

Windows

Import-Certificate -FilePath ".\botserver-stack\conf\system\certificates\ca\ca.crt" -CertStoreLocation Cert:\LocalMachine\Root

Linux

# Ubuntu/Debian
sudo cp ./botserver-stack/conf/system/certificates/ca/ca.crt /usr/local/share/ca-certificates/botserver-ca.crt
sudo update-ca-certificates

# Fedora/RHEL
sudo cp ./botserver-stack/conf/system/certificates/ca/ca.crt /etc/pki/ca-trust/source/anchors/botserver-ca.crt
sudo update-ca-trust

macOS

sudo security add-trusted-cert -d -r trustRoot -k /Library/Keychains/System.keychain ./botserver-stack/conf/system/certificates/ca/ca.crt

Firefox

Firefox uses its own certificate store:

1. Settings → Privacy & Security → View Certificates
2. Authorities → Import
3. Select botserver-stack/conf/system/certificates/ca/ca.crt
4. Check "Trust this CA to identify websites"

---

Troubleshooting

DNS Not Resolving

# Check CoreDNS is running
./botserver status dns

# Test DNS directly
dig @127.0.0.1 api.botserver.local

macOS .local Conflicts

macOS reserves .local for Bonjour. Use the /etc/resolver/ method which doesn't conflict.

Reverting Changes

# Remove hosts entries (Linux/macOS)
sudo sed -i '/botserver\.local/d' /etc/hosts

# Remove macOS resolver
sudo rm /etc/resolver/botserver.local

# Reset DNS (Linux)
sudo rm /etc/systemd/resolved.conf.d/botserver.conf
sudo systemctl restart systemd-resolved

# Reset DNS (Windows)
Set-DnsClientServerAddress -InterfaceAlias $interface -ResetServerAddresses

---

Summary

Access Method	Configuration	Best For
IP Address	None	Default - works immediately, scripts, APIs
hosts file	Minimal	Browser access with friendly URLs
CoreDNS	Low	Development teams, wildcard subdomains

Default recommendation: Use IP addresses for development. No configuration needed.