diff --git a/src/01-introduction/local-domains.md b/src/01-introduction/local-domains.md new file mode 100644 index 00000000..1b59ceff --- /dev/null +++ b/src/01-introduction/local-domains.md @@ -0,0 +1,342 @@ +# 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 + +```bash +# 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 +```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 +```javascript +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 +```rust +use reqwest::Certificate; +use std::fs; + +#[tokio::main] +async fn main() -> Result<(), Box> { + 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: + +```bash +./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`: + +```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):** + +```powershell +@" +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 + +```bash +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 + +```bash +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 + +```powershell +# 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) + +```bash +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 + +```bash +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 + +```powershell +Import-Certificate -FilePath ".\botserver-stack\conf\system\certificates\ca\ca.crt" -CertStoreLocation Cert:\LocalMachine\Root +``` + +### Linux + +```bash +# 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 + +```bash +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 + +```bash +# 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 + +```bash +# 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. diff --git a/src/SUMMARY.md b/src/SUMMARY.md index 2bc906b6..0a2a5063 100644 --- a/src/SUMMARY.md +++ b/src/SUMMARY.md @@ -8,6 +8,7 @@ - [Chapter 01: Run and Talk](./01-introduction/README.md) - [Overview](./01-introduction/overview.md) - [Quick Start](./01-introduction/quick-start.md) + - [Configuring .local Domains](./01-introduction/local-domains.md) - [Installation](./01-introduction/installation.md) - [First Conversation](./01-introduction/first-conversation.md) - [Sessions and Channels](./01-introduction/sessions.md)