GeneralBots/botbook
2
2
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

docs: add local domains configuration guide

Browse source 
- Add new section 'Configuring Local Development Access' after Quick Start
- Document IP-based access as default (zero configuration)
- Document optional hostname access via hosts file or CoreDNS
- Use standardized component names: tables, drive, cache, vectordb
- Include code examples for Python, Node.js, and Rust mTLS
- Add troubleshooting and certificate trust instructions
This commit is contained in:
Rodrigo Rodriguez (Pragmatismo) 2025-12-07 10:41:22 -03:00
parent 7123f881c6
commit ebe7e19ab7
2 changed files with 343 additions and 0 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

342
src/01-introduction/local-domains.md Normal file
View file

@ -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<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:
```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.

1
src/SUMMARY.md
View file

@ -8,6 +8,7 @@
- [Chapter 01: Run and Talk](./01-introduction/README.md) - [Chapter 01: Run and Talk](./01-introduction/README.md)
- [Overview](./01-introduction/overview.md) - [Overview](./01-introduction/overview.md)
- [Quick Start](./01-introduction/quick-start.md) - [Quick Start](./01-introduction/quick-start.md)
- [Configuring .local Domains](./01-introduction/local-domains.md)
- [Installation](./01-introduction/installation.md) - [Installation](./01-introduction/installation.md)
- [First Conversation](./01-introduction/first-conversation.md) - [First Conversation](./01-introduction/first-conversation.md)
- [Sessions and Channels](./01-introduction/sessions.md) - [Sessions and Channels](./01-introduction/sessions.md)