84 lines
3.1 KiB
Markdown
84 lines
3.1 KiB
Markdown
|
# Architecture Decision Record (ADR) - 001: Synology Secure Access
|
||
|
|
|
||
|
|
* **Status**: Accepted
|
||
|
|
* **Date**: 2026-01-18
|
||
|
|
* **Decision Makers**: Development Team (Gemini & Claude)
|
||
|
|
* **Subject**: Secure Remote Access Strategy for Synology Backend services
|
||
|
|
|
||
|
|
## Context & Problem
|
||
|
|
To enable the "Posimai" ecosystem (Sake & Incense apps) to utilize backend services (DB, potentially AI Proxy) hosted on a home Synology NAS, a robust connection strategy is required.
|
||
|
|
Previous attempts using direct IP (`192.168.x.x`) failed due to lack of external access.
|
||
|
|
Previous attempts using pure HTTP failed due to Android/iOS security requirements (Cleartext traffic).
|
||
|
|
|
||
|
|
## Decision
|
||
|
|
We will use **Tailscale MagicDNS with HTTPS Certificates** as the primary connectivity solution for the current development phase.
|
||
|
|
|
||
|
|
### Justification
|
||
|
|
1. **Zero Cost & Zero Hardware**: Tailscale is already running. No new domains or hardware needed.
|
||
|
|
2. **Native HTTPS**: Tailscale provides valid Let's Encrypt certificates for `*.ts.net` domains, satisfying Flutter's secure connection requirements.
|
||
|
|
3. **Secure by Design**: No open ports (Port Forwarding) required on the router. Access is limited to devices in the Tailnet.
|
||
|
|
4. **Sufficiency**: For a user base < 1 person (Developer), the complexity of Cloudflare Tunnel is unnecessary overhead.
|
||
|
|
|
||
|
|
### Alternatives Considered
|
||
|
|
* **Cloudflare Tunnel**: Best for scaling/production (>10k users), but overkill for now.
|
||
|
|
* **QuickConnect**: Synology's proprietary relay. Too slow and hard to integrate with custom ports/containers.
|
||
|
|
* **Direct IP / VPN**: Unstable IP addresses and difficult certificates management.
|
||
|
|
|
||
|
|
## Implementation Roadmap
|
||
|
|
|
||
|
|
### Week 1: Tailscale HTTPS Setup
|
||
|
|
1. **MagicDNS**: Enable in Tailscale Admin Console.
|
||
|
|
2. **HTTPS Certificates**: Enable in Tailscale Admin Console.
|
||
|
|
3. **Result**: `https://posimai-nas.ts.net` becomes a valid, globally accessible (within Tailnet) URL.
|
||
|
|
|
||
|
|
### Week 2: Immich & Container Integration
|
||
|
|
* Deploy `immich` via Container Manager to act as the media cache.
|
||
|
|
* Deploy `posimai-db` (Postgres) for structured data.
|
||
|
|
* Configure `docker-compose.yml` (see below).
|
||
|
|
|
||
|
|
### Week 3: App Integration
|
||
|
|
* Update Flutter App configuration:
|
||
|
|
```dart
|
||
|
|
const String apiBaseUrl = 'https://posimai-nas.ts.net';
|
||
|
|
```
|
||
|
|
|
||
|
|
## Infrastructure Configuration (`docker-compose.yml`)
|
||
|
|
|
||
|
|
```yaml
|
||
|
|
version: '3.8'
|
||
|
|
services:
|
||
|
|
# Main Database
|
||
|
|
posimai-db:
|
||
|
|
image: postgres:15-alpine
|
||
|
|
container_name: posimai-db
|
||
|
|
restart: always
|
||
|
|
environment:
|
||
|
|
POSTGRES_USER: ${DB_USER}
|
||
|
|
POSTGRES_PASSWORD: ${DB_PASSWORD}
|
||
|
|
POSTGRES_DB: posimai_master
|
||
|
|
volumes:
|
||
|
|
- ./pgdata:/var/lib/postgresql/data
|
||
|
|
networks:
|
||
|
|
- posimai-net
|
||
|
|
|
||
|
|
# AI Proxy (Legacy/Backup)
|
||
|
|
posimai-proxy:
|
||
|
|
build: ./ai-proxy
|
||
|
|
container_name: posimai-proxy
|
||
|
|
restart: unless-stopped
|
||
|
|
ports:
|
||
|
|
- "8080:8080"
|
||
|
|
environment:
|
||
|
|
- GEMINI_API_KEY=${GEMINI_API_KEY}
|
||
|
|
networks:
|
||
|
|
- posimai-net
|
||
|
|
|
||
|
|
networks:
|
||
|
|
posimai-net:
|
||
|
|
driver: bridge
|
||
|
|
```
|
||
|
|
|
||
|
|
## Future Considerations
|
||
|
|
* If user base grows > 100, migrate to **Tailscale Funnel** (Public internet access).
|
||
|
|
* If user base grows > 10,000, migrate to **Cloudflare Tunnel** + Custom Domain.
|