154 lines
3.8 KiB
Markdown
154 lines
3.8 KiB
Markdown
---
|
|
title: Self-hosting
|
|
---
|
|
|
|
# Self-hosting
|
|
|
|
Run YAMS on your own infrastructure with full control over data, backups, and operations.
|
|
|
|
**Consider managed hosting if** you want zero-ops, automated backups, and metrics. See [Managed Hosting](managed.md).
|
|
|
|
## Who Should Self-host
|
|
|
|
- Need full control over infrastructure and data locality
|
|
- Prefer your own backup/monitoring stack
|
|
- Have security/compliance requirements limiting SaaS
|
|
- Want to evaluate internally before choosing managed hosting
|
|
|
|
## Quick Start
|
|
|
|
### Docker (Recommended)
|
|
|
|
```bash
|
|
docker run --rm -it ghcr.io/trvon/yams:latest --version
|
|
mkdir -p $HOME/yams-data
|
|
|
|
docker run --rm -it \
|
|
-v $HOME/yams-data:/var/lib/yams \
|
|
ghcr.io/trvon/yams:latest yams init --non-interactive
|
|
|
|
echo "hello from self-hosted yams" | docker run --rm -i \
|
|
-v $HOME/yams-data:/var/lib/yams \
|
|
ghcr.io/trvon/yams:latest yams add - --tags "example,selfhosted"
|
|
|
|
docker run --rm -it \
|
|
-v $HOME/yams-data:/var/lib/yams \
|
|
ghcr.io/trvon/yams:latest yams search "self-hosted"
|
|
```
|
|
|
|
**Note:** Use stable host path (e.g., `/srv/yams`) for servers.
|
|
|
|
### Native Binary
|
|
|
|
See [Installation](../user_guide/installation.md) for platform-specific download and setup steps.
|
|
|
|
### Docker Compose (Optional)
|
|
|
|
```yaml
|
|
version: "3.9"
|
|
services:
|
|
yams:
|
|
image: ghcr.io/trvon/yams:latest
|
|
container_name: yams
|
|
command: ["sleep", "infinity"]
|
|
volumes:
|
|
- /srv/yams:/var/lib/yams
|
|
restart: unless-stopped
|
|
```
|
|
|
|
```bash
|
|
docker compose up -d
|
|
docker exec -it yams yams init --non-interactive
|
|
docker exec -i yams sh -lc 'echo "compose example" | yams add - --tags demo'
|
|
docker exec -it yams yams search "compose"
|
|
```
|
|
|
|
## Data Directory
|
|
|
|
YAMS stores content, indexes, and metadata in a single directory.
|
|
|
|
**Paths:**
|
|
- Linux: `/var/lib/yams`
|
|
- macOS: `/usr/local/var/yams` or `/opt/yams/data`
|
|
- Containers: mount from host to `/var/lib/yams`
|
|
|
|
See [Admin: Operations](../admin/operations.md) for configuration details.
|
|
|
|
## Backups
|
|
|
|
```bash
|
|
systemctl stop yams-daemon || true
|
|
rsync -a --delete /var/lib/yams/ /backups/yams/$(date +%F)/
|
|
systemctl start yams-daemon || true
|
|
```
|
|
|
|
**Best practices:**
|
|
- Quiesce writes during backup (low-traffic windows)
|
|
- Store backups off-site with retention policies
|
|
- Test restores periodically
|
|
|
|
**Logical grouping:**
|
|
```bash
|
|
yams add file --tags "release,2024Q4" --collection "release-v1.0" --snapshot-id "2024Q4"
|
|
```
|
|
|
|
## Upgrades
|
|
|
|
```bash
|
|
# Pin container version
|
|
docker pull ghcr.io/trvon/yams:v0.3.x
|
|
|
|
# Backup before upgrading
|
|
rsync -a /var/lib/yams/ /backups/yams-pre-upgrade/
|
|
|
|
# Review release notes
|
|
# Upgrade binary/container
|
|
# Sanity check
|
|
yams --version
|
|
yams search "<known doc>"
|
|
```
|
|
|
|
## Operations
|
|
|
|
**Health checks:**
|
|
```bash
|
|
yams search "healthcheck-probe" --limit 1 # Run on schedule, alert on failure
|
|
```
|
|
|
|
**Metrics:** Wrap commands with timing/exit-code logging
|
|
|
|
**Logs:** Capture stdout/stderr (systemd, Docker logs)
|
|
|
|
See [Admin: Operations](../admin/operations.md) for deployment and tuning.
|
|
|
|
## Security
|
|
|
|
- Run as non-root user
|
|
- Restrict data directory permissions (0750)
|
|
- Isolate credentials/tokens
|
|
- Encrypt backups at rest, store off-site
|
|
- For remote access: VPN/SSH/zero-trust tunnel
|
|
- For public APIs: reverse proxy or WAF with TLS
|
|
|
|
## Common Tasks
|
|
|
|
See the [Quick Start](../user_guide/README.md) and [CLI Reference](../user_guide/cli.md) for usage examples.
|
|
|
|
## Troubleshooting
|
|
|
|
| Issue | Solution |
|
|
|-------|----------|
|
|
| Command not found | Check install path or Docker image |
|
|
| Permission denied | Check data directory ownership/permissions |
|
|
| No results | Verify ingest: `yams list --limit 5` |
|
|
| Performance | See [Admin: Operations](../admin/operations.md) |
|
|
|
|
Open issues on GitHub with environment details and steps to reproduce.
|
|
|
|
---
|
|
|
|
**Related:**
|
|
- [Installation](../user_guide/installation.md)
|
|
- [Admin: Operations](../admin/operations.md)
|
|
- [Managed Hosting](managed.md)
|
|
- [Pricing](pricing.md)
|