arabica.social
Coffee journaling on ATProto (alpha)
alpha.arabica.social
coffee
1# Arabica Deployment Guide
2
3Quick guide to deploy Arabica to a VPS with Docker and automatic HTTPS.
4
5## Prerequisites
6
7- VPS with Docker and Docker Compose installed
8- Domain name pointing to your VPS IP address (A record)
9- Ports 80 and 443 open in firewall
10
11## Quick Start (Production)
12
131. **Clone the repository:**
14 ```bash
15 git clone <repository-url>
16 cd arabica
17 ```
18
192. **Configure your domain:**
20 ```bash
21 cp .env.example .env
22 nano .env
23 ```
24
25 Update `.env` with your domain:
26 ```env
27 DOMAIN=arabica.yourdomain.com
28 ACME_EMAIL=your-email@example.com
29 ```
30
313. **Deploy:**
32 ```bash
33 docker compose up -d
34 ```
35
36That's it! Caddy will automatically:
37- Obtain SSL certificates from Let's Encrypt
38- Renew certificates before expiry
39- Redirect HTTP to HTTPS
40- Proxy requests to Arabica
41
424. **Check logs:**
43 ```bash
44 docker compose logs -f
45 ```
46
475. **Visit your site:**
48 ```
49 https://arabica.yourdomain.com
50 ```
51
52## Local Development
53
54To run locally without a domain:
55
56```bash
57docker compose up
58```
59
60Then visit `http://localhost` (Caddy will serve on port 80).
61
62## Updating
63
64```bash
65git pull
66docker compose down
67docker compose build
68docker compose up -d
69```
70
71## Troubleshooting
72
73### Certificate Issues
74
75If Let's Encrypt can't issue a certificate:
76- Ensure your domain DNS is pointing to your VPS
77- Check ports 80 and 443 are accessible
78- Check logs: `docker compose logs caddy`
79
80### View Arabica logs
81
82```bash
83docker compose logs -f arabica
84```
85
86### Reset everything
87
88```bash
89docker compose down -v # Warning: deletes all data
90docker compose up -d
91```
92
93## Production Checklist
94
95- [ ] Domain DNS pointing to VPS
96- [ ] Ports 80 and 443 open in firewall
97- [ ] `.env` file configured with your domain
98- [ ] Valid email set for Let's Encrypt notifications
99- [ ] Regular backups of `arabica-data` volume
100
101## Backup
102
103To backup user data:
104
105```bash
106docker compose exec arabica cp /data/arabica.db /data/arabica-backup.db
107docker cp $(docker compose ps -q arabica):/data/arabica-backup.db ./backup-$(date +%Y%m%d).db
108```
109
110## Advanced Configuration
111
112### Custom Caddyfile
113
114Edit `Caddyfile` directly for advanced options like:
115- Rate limiting
116- Custom headers
117- IP whitelisting
118- Multiple domains
119
120### Environment Variables
121
122All available environment variables in `.env`:
123
124| Variable | Default | Description |
125| ------------------- | ------------------------------------ | ------------------------------- |
126| `DOMAIN` | localhost | Your domain name |
127| `ACME_EMAIL` | (empty) | Email for Let's Encrypt |
128| `LOG_LEVEL` | info | debug/info/warn/error |
129| `LOG_FORMAT` | json | console/json |
130| `SERVER_PUBLIC_URL` | https://${DOMAIN} | Override public URL |
131| `SECURE_COOKIES` | true | Use secure cookies |
132
133## Support
134
135For issues, check the logs first:
136```bash
137docker compose logs
138```