docs: add local domains configuration guide
- 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:
parent
7123f881c6
commit
ebe7e19ab7
2 changed files with 343 additions and 0 deletions
342
src/01-introduction/local-domains.md
Normal file
342
src/01-introduction/local-domains.md
Normal 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.
|
||||
|
|
@ -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)
|
||||
|
|
|
|||
Loading…
Add table
Reference in a new issue