Enhance README and RPC for package management
- Added instructions to README.md for building an ISO from source and flashing it to USB. - Introduced a new RPC method for package installation, including security checks and container management. - Updated Docker and Podman integration in build scripts to support both container runtimes. - Enhanced Nginx configuration for improved timeout settings and WebSocket support. - Added new app metadata for additional applications in the Docker package scanner.
This commit is contained in:
Dorian
@@ -0,0 +1,316 @@
|
||||
# Package Installation Architecture & Security
|
||||
|
||||
## Overview
|
||||
|
||||
Archipelago uses a **container-based app installation system** similar to StartOS, with enhanced security and flexibility.
|
||||
|
||||
## Installation Methods
|
||||
|
||||
### 1. **Web UI Marketplace** (Current Implementation)
|
||||
**How it works:**
|
||||
- User clicks "Install" in the marketplace
|
||||
- Frontend calls `package.install` RPC method
|
||||
- Backend pulls Docker image and creates Podman container
|
||||
- Container starts with predefined configuration
|
||||
|
||||
**Security:**
|
||||
- ✅ Image name validation (prevents injection attacks)
|
||||
- ✅ Resource limits (CPU, memory)
|
||||
- ⚠️ Uses hardcoded configs (will use manifests)
|
||||
- ⚠️ No image signature verification yet
|
||||
|
||||
**Pros:**
|
||||
- User-friendly (click to install)
|
||||
- Fast installation
|
||||
- Works for most Docker-based apps
|
||||
|
||||
**Cons:**
|
||||
- Limited configuration options
|
||||
- No manifest-based permissions yet
|
||||
- Requires internet for image pull
|
||||
|
||||
---
|
||||
|
||||
### 2. **Manifest-Based Installation** (Recommended Future)
|
||||
|
||||
**How it works:**
|
||||
```yaml
|
||||
# apps/home-assistant/manifest.yml
|
||||
app:
|
||||
id: home-assistant
|
||||
name: Home Assistant
|
||||
container:
|
||||
image: homeassistant/home-assistant:2024.1
|
||||
image_signature: cosign://... # Verify with Cosign
|
||||
security:
|
||||
capabilities: [NET_BIND_SERVICE]
|
||||
readonly_root: false
|
||||
network_policy: host
|
||||
resources:
|
||||
cpu_limit: 2
|
||||
memory_limit: 2Gi
|
||||
```
|
||||
|
||||
**Installation:**
|
||||
```bash
|
||||
# Backend reads manifest, validates, creates container with exact specs
|
||||
archipelago install --manifest apps/home-assistant/manifest.yml
|
||||
```
|
||||
|
||||
**Security Benefits:**
|
||||
- ✅ **Image verification** with Cosign signatures
|
||||
- ✅ **Explicit permissions** (capabilities, network access)
|
||||
- ✅ **Resource limits** from manifest
|
||||
- ✅ **Dependency resolution** (Bitcoin Core before LND)
|
||||
- ✅ **AppArmor/SELinux profiles** per app
|
||||
- ✅ **Audit trail** of what permissions were granted
|
||||
|
||||
---
|
||||
|
||||
### 3. **Sideload from .s9pk** (StartOS Compatible)
|
||||
|
||||
**How it works:**
|
||||
- User uploads `.s9pk` file (ZIP with manifest + Docker image)
|
||||
- Backend extracts, verifies signature
|
||||
- Creates container from embedded image
|
||||
|
||||
**Security:**
|
||||
- ✅ GPG signature verification
|
||||
- ✅ Offline installation (no internet needed)
|
||||
- ✅ User reviews permissions before install
|
||||
|
||||
---
|
||||
|
||||
## Security Considerations
|
||||
|
||||
### Current Implementation (package.install)
|
||||
|
||||
#### ✅ **What's Secure:**
|
||||
1. **Input Validation**
|
||||
```rust
|
||||
fn is_valid_docker_image(image: &str) -> bool {
|
||||
// Rejects shell metacharacters: & | ; ` $ ( ) < >
|
||||
// Prevents command injection
|
||||
}
|
||||
```
|
||||
|
||||
2. **Resource Limits**
|
||||
```rust
|
||||
run_args.push("--memory=2g");
|
||||
run_args.push("--cpus=2");
|
||||
```
|
||||
|
||||
3. **Rootless Podman** (future)
|
||||
- Containers run as non-root user
|
||||
- Reduced attack surface
|
||||
|
||||
#### ⚠️ **What Needs Improvement:**
|
||||
|
||||
1. **No Image Verification**
|
||||
- **Current**: Trusts Docker Hub/registries blindly
|
||||
- **Should**: Verify signatures with Cosign
|
||||
```bash
|
||||
cosign verify --key cosign.pub ghcr.io/owner/image:tag
|
||||
```
|
||||
|
||||
2. **Hardcoded Configs**
|
||||
- **Current**: `get_app_config()` has hardcoded ports/volumes
|
||||
- **Should**: Load from `apps/*/manifest.yml`
|
||||
|
||||
3. **No Permission Review**
|
||||
- **Current**: User doesn't see what access app gets
|
||||
- **Should**: Show permission prompt before install:
|
||||
```
|
||||
Home Assistant requests:
|
||||
- Network: Host (for device discovery)
|
||||
- Devices: /dev/ttyUSB0 (serial devices)
|
||||
- Capabilities: NET_BIND_SERVICE
|
||||
- Storage: 10GB
|
||||
|
||||
[Cancel] [Install]
|
||||
```
|
||||
|
||||
4. **No Dependency Resolution**
|
||||
- **Current**: Install apps independently
|
||||
- **Should**: Check dependencies (e.g., LND requires Bitcoin Core)
|
||||
|
||||
5. **No Network Isolation**
|
||||
- **Current**: Apps can access each other
|
||||
- **Should**: Isolated networks by default, explicit connections
|
||||
|
||||
---
|
||||
|
||||
##Security Best Practices
|
||||
|
||||
### Multi-Layer Security Model
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────┐
|
||||
│ 1. Supply Chain Security │
|
||||
│ - Cosign image signing │
|
||||
│ - SBOM (Software Bill of Materials) │
|
||||
│ - Vulnerability scanning │
|
||||
└─────────────────────────────────────────────┘
|
||||
↓
|
||||
┌─────────────────────────────────────────────┐
|
||||
│ 2. Installation Validation │
|
||||
│ - Signature verification │
|
||||
│ - Manifest schema validation │
|
||||
│ - Permission review │
|
||||
└─────────────────────────────────────────────┘
|
||||
↓
|
||||
┌─────────────────────────────────────────────┐
|
||||
│ 3. Runtime Isolation │
|
||||
│ - Rootless containers │
|
||||
│ - AppArmor/SELinux profiles │
|
||||
│ - Network isolation │
|
||||
│ - Resource limits │
|
||||
└─────────────────────────────────────────────┘
|
||||
↓
|
||||
┌─────────────────────────────────────────────┐
|
||||
│ 4. Monitoring & Audit │
|
||||
│ - Health checks │
|
||||
│ - Log collection │
|
||||
│ - Anomaly detection │
|
||||
└─────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Comparison with StartOS
|
||||
|
||||
| Feature | StartOS | Archipelago (Current) | Archipelago (Goal) |
|
||||
|---------|---------|----------------------|-------------------|
|
||||
| **Image Format** | .s9pk (custom) | Docker images | Both |
|
||||
| **Image Verification** | GPG signatures | ❌ None | ✅ Cosign |
|
||||
| **Permission System** | ✅ Manifest-based | ❌ Hardcoded | ✅ Manifest-based |
|
||||
| **Network Isolation** | ✅ Per-app networks | ❌ Shared network | ✅ Per-app networks |
|
||||
| **Dependency Resolution** | ✅ Automatic | ❌ Manual | ✅ Automatic |
|
||||
| **Resource Limits** | ✅ From manifest | ⚠️ Hardcoded | ✅ From manifest |
|
||||
| **Audit Trail** | ✅ Yes | ⚠️ Basic logs | ✅ Full audit |
|
||||
|
||||
---
|
||||
|
||||
## Recommended Next Steps
|
||||
|
||||
### Phase 1: Manifest-Based Installation (Priority: HIGH)
|
||||
1. Implement manifest parser in Rust
|
||||
2. Load configs from `apps/*/manifest.yml`
|
||||
3. Apply security policies from manifest
|
||||
4. Show permission prompt in UI
|
||||
|
||||
### Phase 2: Image Verification (Priority: HIGH)
|
||||
1. Integrate Cosign for signature verification
|
||||
2. Maintain whitelist of trusted signing keys
|
||||
3. Reject unsigned images in production
|
||||
|
||||
### Phase 3: Network Isolation (Priority: MEDIUM)
|
||||
1. Create isolated network per app
|
||||
2. Explicit inter-app connections (e.g., LND → Bitcoin Core RPC)
|
||||
3. Firewall rules per app
|
||||
|
||||
### Phase 4: Dependency Resolution (Priority: MEDIUM)
|
||||
1. Parse `dependencies` from manifests
|
||||
2. Auto-install dependencies
|
||||
3. Prevent removal of depended-upon apps
|
||||
|
||||
### Phase 5: Advanced Security (Priority: LOW)
|
||||
1. AppArmor profile generation per app
|
||||
2. Hardware attestation (TPM 2.0)
|
||||
3. Encrypted secrets storage (not plaintext volumes)
|
||||
|
||||
---
|
||||
|
||||
## How Users Will Install Apps (Production)
|
||||
|
||||
### Method 1: Trusted Marketplace (Recommended)
|
||||
```
|
||||
User → Marketplace → Verified Registry → Podman
|
||||
```
|
||||
- Pre-vetted apps with verified signatures
|
||||
- Manifests reviewed by Archipelago team
|
||||
- One-click install
|
||||
|
||||
### Method 2: Sideload (.s9pk)
|
||||
```
|
||||
User → Upload .s9pk → Verify Signature → Extract → Podman
|
||||
```
|
||||
- For community apps
|
||||
- User takes responsibility for trust
|
||||
|
||||
### Method 3: Advanced (Manual)
|
||||
```
|
||||
User → SSH → podman run with manifest → Manual config
|
||||
```
|
||||
- For developers/power users
|
||||
- Full control, no guardrails
|
||||
|
||||
---
|
||||
|
||||
## Security Philosophy
|
||||
|
||||
**Defense in Depth:**
|
||||
- Never trust a single layer
|
||||
- Verify at supply chain (Cosign)
|
||||
- Isolate at runtime (containers)
|
||||
- Monitor continuously (health checks)
|
||||
|
||||
**Principle of Least Privilege:**
|
||||
- Apps get only what they need
|
||||
- Explicit permissions in manifest
|
||||
- User approves before granting
|
||||
|
||||
**Transparency:**
|
||||
- Open manifests (readable YAML)
|
||||
- Clear permission requests
|
||||
- Audit logs of all actions
|
||||
|
||||
---
|
||||
|
||||
## Questions Answered
|
||||
|
||||
### Is package.install secure?
|
||||
**Current state:** Moderately secure
|
||||
- ✅ Input validation prevents injection
|
||||
- ✅ Resource limits prevent resource exhaustion
|
||||
- ❌ No image verification (trust Docker Hub)
|
||||
- ❌ No permission system yet
|
||||
|
||||
**With manifests:** Very secure
|
||||
- ✅ All of the above
|
||||
- ✅ Signature verification
|
||||
- ✅ Explicit permissions
|
||||
- ✅ Network isolation
|
||||
|
||||
### How do users install on actual OS?
|
||||
1. **Pre-installed in ISO**: Included in image build
|
||||
2. **Web UI Marketplace**: Click to install (current)
|
||||
3. **Sideload**: Upload .s9pk file
|
||||
4. **CLI**: SSH + podman commands (advanced)
|
||||
|
||||
The **Web UI is the primary method** for end users - simple, secure, auditable.
|
||||
|
||||
---
|
||||
|
||||
## Implementation Roadmap
|
||||
|
||||
**v0.1.0 (Current):**
|
||||
- ✅ Basic `package.install` RPC
|
||||
- ✅ Hardcoded app configs
|
||||
- ✅ Input validation
|
||||
|
||||
**v0.2.0 (Next):**
|
||||
- Manifest parser
|
||||
- Load from `apps/*/manifest.yml`
|
||||
- Permission UI prompt
|
||||
|
||||
**v0.3.0:**
|
||||
- Cosign verification
|
||||
- Network isolation per app
|
||||
- Dependency resolution
|
||||
|
||||
**v1.0.0:**
|
||||
- Full security model
|
||||
- AppArmor profiles
|
||||
- Audit logging
|
||||
- Production-ready
|
||||
@@ -0,0 +1,182 @@
|
||||
# Tailscale Integration Guide
|
||||
|
||||
## Overview
|
||||
|
||||
Archipelago integrates with Tailscale to provide secure remote access via your personal VPN mesh network. When Tailscale is installed, users can access their Archipelago UI from anywhere using their Tailscale network.
|
||||
|
||||
## Automatic Configuration
|
||||
|
||||
### Installation Process
|
||||
|
||||
When a user installs Tailscale from the Archipelago App Store:
|
||||
|
||||
1. **Container Setup** (automatic)
|
||||
- Tailscale container runs with `--network=host` and `--privileged` mode
|
||||
- Creates `/var/lib/archipelago/tailscale` for persistent state
|
||||
- Starts Tailscale daemon and web UI on port 8240
|
||||
|
||||
2. **User Authentication** (user action required)
|
||||
- User clicks "Launch" on Tailscale app
|
||||
- Opens web UI at `http://<local-ip>:8240`
|
||||
- User logs in with their Tailscale account
|
||||
- Device registers to their tailnet
|
||||
|
||||
3. **Network Configuration** (automatic)
|
||||
- `tailscale0` interface is created with Tailscale IP (e.g., `100.91.10.103`)
|
||||
- Nginx detects the new interface and adds it to listen directives
|
||||
- Archipelago UI becomes accessible via Tailscale hostname
|
||||
|
||||
### Accessing via Tailscale
|
||||
|
||||
After setup, users can access Archipelago from any device on their tailnet:
|
||||
|
||||
```
|
||||
http://<hostname>.tail<xxxxxx>.ts.net/
|
||||
```
|
||||
|
||||
Example: `http://archipelago.tail2b6225.ts.net/`
|
||||
|
||||
## Technical Implementation
|
||||
|
||||
### Container Configuration
|
||||
|
||||
Tailscale requires special container permissions:
|
||||
|
||||
```rust
|
||||
// In rpc.rs - handle_package_install()
|
||||
if package_id == "tailscale" {
|
||||
run_args.push("--network=host"); // Access host network
|
||||
run_args.push("--privileged"); // Full container capabilities
|
||||
run_args.push("--cap-add=NET_ADMIN"); // Network administration
|
||||
run_args.push("--cap-add=NET_RAW"); // Raw packet access
|
||||
run_args.push("--device=/dev/net/tun"); // TUN device for VPN
|
||||
}
|
||||
```
|
||||
|
||||
### Nginx Configuration
|
||||
|
||||
The `configure-tailscale-nginx.sh` script automatically:
|
||||
|
||||
1. Detects the Tailscale IP from `tailscale0` interface
|
||||
2. Adds `listen <tailscale-ip>:80;` to Nginx config
|
||||
3. Reloads Nginx to accept connections from tailnet
|
||||
|
||||
### Post-Installation Automation
|
||||
|
||||
A systemd service (`archipelago-tailscale.service`) runs after Archipelago starts:
|
||||
|
||||
- Waits for `tailscale0` interface to exist
|
||||
- Runs configuration script
|
||||
- Ensures Nginx is ready for tailnet connections
|
||||
|
||||
## User Experience Flow
|
||||
|
||||
### First-Time Setup
|
||||
|
||||
1. **User installs Tailscale** from App Store
|
||||
- Container downloads and starts
|
||||
- "Launch" button appears in My Apps
|
||||
|
||||
2. **User authenticates**
|
||||
- Clicks "Launch" → opens web UI
|
||||
- Logs in with Tailscale account
|
||||
- Approves device in Tailscale admin console
|
||||
|
||||
3. **Automatic configuration**
|
||||
- System detects Tailscale connection
|
||||
- Nginx reconfigures automatically
|
||||
- User receives tailnet hostname
|
||||
|
||||
4. **Remote access enabled**
|
||||
- User can now access from anywhere
|
||||
- All devices on their tailnet can connect
|
||||
- Uses Tailscale's encrypted mesh network
|
||||
|
||||
### Ongoing Usage
|
||||
|
||||
- **No maintenance required** - Tailscale auto-starts with system
|
||||
- **Automatic reconnection** - Container restart policy handles disconnects
|
||||
- **Persistent state** - Authentication survives reboots
|
||||
- **Web UI always available** - Manage Tailscale at port 8240
|
||||
|
||||
## Security Considerations
|
||||
|
||||
### Why Privileged Mode?
|
||||
|
||||
Tailscale requires privileged mode because it:
|
||||
- Creates a TUN device for VPN traffic
|
||||
- Modifies iptables rules for routing
|
||||
- Manages network interfaces on the host
|
||||
|
||||
### Network Isolation
|
||||
|
||||
- Tailscale runs in host network mode (no container network isolation)
|
||||
- Only users on the same tailnet can access the Archipelago UI
|
||||
- Tailscale provides authentication and encryption
|
||||
|
||||
### Data Persistence
|
||||
|
||||
- Tailscale state is stored in `/var/lib/archipelago/tailscale/`
|
||||
- Contains device identity and credentials
|
||||
- Persists across container recreations
|
||||
- Automatically backed up with system
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Tailscale UI Not Loading
|
||||
|
||||
If the web UI doesn't load:
|
||||
|
||||
```bash
|
||||
# Check container status
|
||||
sudo podman ps --filter name=tailscale
|
||||
|
||||
# Check logs
|
||||
sudo podman logs tailscale
|
||||
|
||||
# Verify interface
|
||||
ip addr show tailscale0
|
||||
|
||||
# Check Nginx configuration
|
||||
sudo nginx -t
|
||||
sudo systemctl status nginx
|
||||
```
|
||||
|
||||
### Remote Access Not Working
|
||||
|
||||
If Tailscale hostname doesn't resolve:
|
||||
|
||||
```bash
|
||||
# Check Tailscale status
|
||||
sudo podman exec tailscale tailscale status
|
||||
|
||||
# Verify Nginx is listening on Tailscale IP
|
||||
sudo netstat -tlnp | grep :80
|
||||
|
||||
# Re-run configuration script
|
||||
sudo /opt/archipelago/scripts/configure-tailscale-nginx.sh
|
||||
```
|
||||
|
||||
### Container Won't Start
|
||||
|
||||
If container fails to start:
|
||||
|
||||
```bash
|
||||
# Check for permission issues
|
||||
sudo dmesg | grep -i deny
|
||||
|
||||
# Verify TUN device exists
|
||||
ls -l /dev/net/tun
|
||||
|
||||
# Check SELinux/AppArmor
|
||||
sudo ausearch -m avc -ts recent # SELinux
|
||||
sudo dmesg | grep -i apparmor # AppArmor
|
||||
```
|
||||
|
||||
## Future Enhancements
|
||||
|
||||
- **Automatic hostname detection** - Display tailnet URL in UI
|
||||
- **MagicDNS support** - Use short hostnames (just `archipelago`)
|
||||
- **Subnet routing** - Route to other networks via Archipelago
|
||||
- **Exit node mode** - Use Archipelago as internet gateway
|
||||
- **ACL integration** - Fine-grained access control via Tailscale ACLs
|
||||
@@ -0,0 +1,214 @@
|
||||
# How to Set Up Remote Access with Tailscale
|
||||
|
||||
Tailscale provides secure remote access to your Archipelago server from anywhere in the world using a zero-config VPN.
|
||||
|
||||
## Installation
|
||||
|
||||
1. **Install Tailscale from App Store**
|
||||
- Navigate to "App Store" in your Archipelago UI
|
||||
- Find "Tailscale" in the available apps
|
||||
- Click "Install"
|
||||
- Wait for installation to complete (container download)
|
||||
|
||||
2. **Access Setup Interface**
|
||||
- Go to "My Apps"
|
||||
- Find "Tailscale" in your installed apps
|
||||
- Click the **"Launch"** button
|
||||
- This opens the Tailscale web interface at `http://<your-ip>:8240`
|
||||
|
||||
## First-Time Setup
|
||||
|
||||
### Step 1: Sign In to Tailscale
|
||||
|
||||
When you click "Launch", you'll see the Tailscale web interface:
|
||||
|
||||
1. Click **"Sign in"** or **"Get Started"**
|
||||
2. You'll be prompted to authenticate with:
|
||||
- **Google** account
|
||||
- **Microsoft** account
|
||||
- **GitHub** account
|
||||
- Or create a new Tailscale account
|
||||
|
||||
3. Follow the authentication flow in your browser
|
||||
|
||||
### Step 2: Authorize the Device
|
||||
|
||||
After signing in:
|
||||
|
||||
1. Your Archipelago server will appear as a new device
|
||||
2. The device will be named something like `archipelago` or based on your hostname
|
||||
3. You may need to approve the device in your Tailscale admin console
|
||||
|
||||
### Step 3: Access Remotely
|
||||
|
||||
Once connected, you can access your Archipelago UI from anywhere:
|
||||
|
||||
**Via Tailscale Hostname:**
|
||||
```
|
||||
http://archipelago.tail<xxxxxx>.ts.net/
|
||||
```
|
||||
|
||||
**Via Tailscale IP:**
|
||||
```
|
||||
http://100.x.x.x/
|
||||
```
|
||||
|
||||
Your exact hostname and IP will be shown in the Tailscale web interface.
|
||||
|
||||
## Using Tailscale
|
||||
|
||||
### From Other Devices
|
||||
|
||||
To access your Archipelago from another device:
|
||||
|
||||
1. **Install Tailscale** on that device (phone, laptop, etc.)
|
||||
- iOS: Download from App Store
|
||||
- Android: Download from Play Store
|
||||
- Mac/Windows/Linux: Download from tailscale.com
|
||||
|
||||
2. **Sign in** with the same account you used for your Archipelago
|
||||
|
||||
3. **Connect** - Your devices are now on the same private network
|
||||
|
||||
4. **Access** your Archipelago using the tailnet hostname or IP
|
||||
|
||||
### Sharing Access
|
||||
|
||||
You can share your Archipelago with trusted users:
|
||||
|
||||
1. Open Tailscale admin console at https://login.tailscale.com/admin/machines
|
||||
2. Click on your Archipelago device
|
||||
3. Click **"Share"**
|
||||
4. Enter the email addresses of people you want to share with
|
||||
5. They'll receive an invitation to join your tailnet
|
||||
|
||||
## Managing Tailscale
|
||||
|
||||
### View Status
|
||||
|
||||
Click **"Launch"** on the Tailscale app in "My Apps" to:
|
||||
- See your tailnet hostname and IP
|
||||
- View connected devices
|
||||
- Check connection status
|
||||
- Manage device settings
|
||||
|
||||
### Stop/Start Tailscale
|
||||
|
||||
- **Stop**: Click the "Stop" button in "My Apps" - This disconnects your server from the tailnet
|
||||
- **Start**: Click the "Start" button to reconnect
|
||||
|
||||
### Disable Remote Access
|
||||
|
||||
If you want to temporarily disable remote access:
|
||||
|
||||
1. Go to "My Apps"
|
||||
2. Click "Stop" on Tailscale
|
||||
3. Remote access is now disabled (local network access still works)
|
||||
|
||||
### Uninstall Tailscale
|
||||
|
||||
To completely remove Tailscale:
|
||||
|
||||
1. Go to "My Apps"
|
||||
2. Click the "⋮" menu on Tailscale
|
||||
3. Select "Remove"
|
||||
4. Confirm removal
|
||||
|
||||
**Note**: Your Tailscale account and device registration remain intact if you want to reinstall later.
|
||||
|
||||
## Security & Privacy
|
||||
|
||||
### What Tailscale Can See
|
||||
|
||||
Tailscale operates on a zero-trust model:
|
||||
- ✅ **End-to-end encrypted** - All traffic is encrypted between your devices
|
||||
- ✅ **Peer-to-peer** - Direct connections when possible (no relay server)
|
||||
- ✅ **No data access** - Tailscale cannot see your traffic or data
|
||||
- ✅ **Open source** - Client and protocol are open source
|
||||
|
||||
### Best Practices
|
||||
|
||||
1. **Use Strong Authentication**
|
||||
- Enable 2FA on your Tailscale account
|
||||
- Use a strong password for your Archipelago login
|
||||
|
||||
2. **Review Connected Devices**
|
||||
- Regularly check which devices are on your tailnet
|
||||
- Remove devices you no longer use
|
||||
|
||||
3. **Share Carefully**
|
||||
- Only share access with trusted users
|
||||
- Use time-limited sharing when possible
|
||||
|
||||
4. **Keep Updated**
|
||||
- Tailscale auto-updates in the container
|
||||
- Archipelago notifies you of available updates
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### "Launch" Button Missing
|
||||
|
||||
If you don't see a Launch button:
|
||||
|
||||
1. **Check container status** - Ensure Tailscale is running in "My Apps"
|
||||
2. **Wait a moment** - Backend detects the port automatically after a few seconds
|
||||
3. **Refresh the page** - Force a UI update
|
||||
|
||||
### Can't Access Web Interface
|
||||
|
||||
If `http://<your-ip>:8240` doesn't load:
|
||||
|
||||
1. **Verify container is running**: Check "My Apps" shows Tailscale as "Running"
|
||||
2. **Check firewall**: Ensure port 8240 isn't blocked on your local network
|
||||
3. **Try localhost**: If on the same machine, try `http://localhost:8240`
|
||||
|
||||
### Remote Access Not Working
|
||||
|
||||
If you can't access via the Tailscale hostname:
|
||||
|
||||
1. **Verify authentication**: Make sure you completed the sign-in flow
|
||||
2. **Check other devices**: Ensure your other device is also signed into Tailscale
|
||||
3. **Wait for DNS**: MagicDNS can take a minute to propagate
|
||||
4. **Use IP instead**: Try accessing via the Tailscale IP (100.x.x.x)
|
||||
|
||||
### Device Not Appearing in Tailscale
|
||||
|
||||
If your Archipelago doesn't show up in your tailnet:
|
||||
|
||||
1. **Complete setup**: Make sure you clicked "Launch" and signed in
|
||||
2. **Check logs**: In "My Apps", click on Tailscale and view logs
|
||||
3. **Restart**: Try stopping and starting the Tailscale app
|
||||
4. **Reinstall**: If all else fails, remove and reinstall Tailscale
|
||||
|
||||
## Advanced Features
|
||||
|
||||
### MagicDNS
|
||||
|
||||
Tailscale provides automatic DNS resolution:
|
||||
- Access by hostname: `http://archipelago/` (shorter URL)
|
||||
- No need to remember IPs
|
||||
- Enabled by default
|
||||
|
||||
### Subnet Routes
|
||||
|
||||
Make your home network accessible via Tailscale:
|
||||
|
||||
1. Open Tailscale web interface
|
||||
2. Go to Settings → Subnet routes
|
||||
3. Add your local subnet (e.g., `192.168.1.0/24`)
|
||||
4. Approve in Tailscale admin console
|
||||
|
||||
### Exit Node
|
||||
|
||||
Use your Archipelago as an internet gateway:
|
||||
|
||||
1. Enable exit node in Tailscale settings
|
||||
2. Connect from another device
|
||||
3. Route all internet traffic through your Archipelago
|
||||
|
||||
## More Information
|
||||
|
||||
- **Tailscale Documentation**: https://tailscale.com/kb/
|
||||
- **Tailscale Status Page**: https://status.tailscale.com/
|
||||
- **Community Support**: https://forum.tailscale.com/
|
||||
- **Archipelago Docs**: See `/docs/TAILSCALE-INTEGRATION.md` for technical details
|
||||
Reference in New Issue
Block a user