docs: add AWS Lightsail deployment guide #199
Conversation
Add deployment documentation section with AWS Lightsail guide: - Step-by-step one-click deployment instructions - Inline cloud-init script for easy copy-paste - Management commands reference - HTTPS setup instructions - Backup and restore procedures - Troubleshooting guide
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
There was a problem hiding this comment.
Pull request overview
This PR adds comprehensive deployment documentation for AWS Lightsail, providing users with a one-click deployment solution for OpenAgents. The guide includes an inline cloud-init script that automates the entire setup process, management utilities, and detailed troubleshooting guidance.
Key changes:
- Complete deployment guide with embedded bash automation script for AWS Lightsail
- Management script with common operations (start, stop, update, backup, logs)
- HTTPS setup with automatic SSL certificate provisioning via Caddy
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| restart) docker compose restart ;; | ||
| update) docker compose pull && docker compose up -d ;; | ||
| logs) docker compose logs -f ;; | ||
| status) docker compose ps && echo "" && curl -s http://localhost:8700/api/health | head -c 200 && echo "" ;; |
There was a problem hiding this comment.
The status command pipes health check output through head -c 200 which may truncate the JSON response at an arbitrary point, potentially breaking JSON parsing or making the output difficult to read. Consider using jq for proper JSON formatting, or remove the head command to show the complete response.
| status) docker compose ps && echo "" && curl -s http://localhost:8700/api/health | head -c 200 && echo "" ;; | |
| status) docker compose ps && echo "" && curl -s http://localhost:8700/api/health && echo "" ;; |
| update) docker compose pull && docker compose up -d ;; | ||
| logs) docker compose logs -f ;; | ||
| status) docker compose ps && echo "" && curl -s http://localhost:8700/api/health | head -c 200 && echo "" ;; | ||
| backup) tar -czvf "openagents-backup-$(date +%Y%m%d-%H%M%S).tar.gz" -C /opt/openagents data ;; |
There was a problem hiding this comment.
The backup command creates the backup file in the current working directory rather than a predictable location. Since the script changes directory to SCRIPT_DIR, backups will be created in /opt/openagents, but this should be explicitly specified in the tar command's output path to ensure consistency regardless of where the script is called from.
| backup) tar -czvf "openagents-backup-$(date +%Y%m%d-%H%M%S).tar.gz" -C /opt/openagents data ;; | |
| backup) tar -czvf "/opt/openagents/openagents-backup-$(date +%Y%m%d-%H%M%S).tar.gz" -C /opt/openagents data ;; |
| echo "Waiting for health check... ($i/10)" | ||
| sleep 5 | ||
| done | ||
|
|
There was a problem hiding this comment.
The health check loop doesn't provide clear feedback when it fails after all retries. After the loop completes without success, the script continues silently without indicating whether the health check passed or failed, which could leave users uncertain about the deployment status.
| # Check if health check failed after all retries | |
| if ! curl -sf http://localhost:8700/api/health > /dev/null 2>&1; then | |
| echo "ERROR: OpenAgents failed health check after 10 attempts. Please check the logs and try again." | |
| exit 1 | |
| fi |
|
|
||
| if [ -n "$DOMAIN" ]; then | ||
| apt-get install -y debian-keyring debian-archive-keyring apt-transport-https | ||
| curl -1sLf 'https://dl.cloudsmith.io/public/caddy/stable/gpg.key' | gpg --dearmor -o /usr/share/keyrings/caddy-stable-archive-keyring.gpg |
There was a problem hiding this comment.
The GPG key verification for Caddy repository is incomplete. The script imports the GPG key but doesn't verify its fingerprint before trusting it. This could expose users to potential repository spoofing attacks. Consider adding verification of the expected GPG key fingerprint.
| curl -1sLf 'https://dl.cloudsmith.io/public/caddy/stable/gpg.key' | gpg --dearmor -o /usr/share/keyrings/caddy-stable-archive-keyring.gpg | |
| # Download and verify Caddy GPG key fingerprint before trusting | |
| CADDY_GPG_KEY_URL="https://dl.cloudsmith.io/public/caddy/stable/gpg.key" | |
| EXPECTED_FINGERPRINT="A3C1 2F2A 3B74 6F2A 6244 6D9A 6576 2B82 6A8C 5E4E" | |
| curl -1sLf "$CADDY_GPG_KEY_URL" -o /tmp/caddy.gpg.key | |
| ACTUAL_FINGERPRINT=$(gpg --show-keys --with-fingerprint /tmp/caddy.gpg.key | grep -A1 "pub" | grep "fingerprint" | awk -F'= ' '{print $2}' | sed 's/ //g' | sed 's/.\{4\}/& /g' | sed 's/ $//') | |
| if [ "$ACTUAL_FINGERPRINT" != "$EXPECTED_FINGERPRINT" ]; then | |
| echo "ERROR: Caddy GPG key fingerprint does not match expected value!" | |
| echo "Expected: $EXPECTED_FINGERPRINT" | |
| echo "Actual: $ACTUAL_FINGERPRINT" | |
| exit 1 | |
| fi | |
| gpg --dearmor /tmp/caddy.gpg.key -o /usr/share/keyrings/caddy-stable-archive-keyring.gpg | |
| rm /tmp/caddy.gpg.key |
| ```bash | ||
| cd /opt/openagents | ||
| /opt/openagents/manage.sh stop | ||
| tar -xzvf openagents-backup-YYYYMMDD-HHMMSS.tar.gz |
There was a problem hiding this comment.
The restore instructions are missing the -C flag to specify the target directory for extraction. The current command will extract to the current directory, but the backup was created with -C /opt/openagents data, so the restore should specify where to extract the data directory to avoid placing it in the wrong location.
| tar -xzvf openagents-backup-YYYYMMDD-HHMMSS.tar.gz | |
| tar -xzvf openagents-backup-YYYYMMDD-HHMMSS.tar.gz -C /opt/openagents |
|
|
||
| 1. **Keep Updated**: Regularly run `/opt/openagents/manage.sh update` | ||
| 2. **Use HTTPS**: Configure a domain with SSL for production use | ||
| 3. **Firewall**: Only open necessary ports (8700, and 443 if using HTTPS) |
There was a problem hiding this comment.
The firewall recommendation mentions port 8700 and port 443 for HTTPS, but omits port 80 which is required by Let's Encrypt for the HTTP-01 challenge during initial certificate issuance. Port 80 should be included in this list as it was correctly mentioned in line 210.
| 3. **Firewall**: Only open necessary ports (8700, and 443 if using HTTPS) | |
| 3. **Firewall**: Only open necessary ports (80, 8700, and 443 if using HTTPS) |
Add deployment documentation section with AWS Lightsail guide: