FAQ & Troubleshooting
Common questions and solutions. If you're stuck, email support@xeroops.com with your xeroops status output.
Your license is bound to a specific AWS account ID. The account you're currently authenticated as doesn't match. Run:
aws sts get-caller-identityCompare the Account value to the account_id field in your license.json. They must match exactly. If you have multiple AWS profiles, use AWS_PROFILE=your-profile xeroops activate ....
No. Each license is cryptographically bound to one AWS account ID and validated on every command via IMDSv2. If you need to run in a second account, purchase a second license or contact us to discuss your use case.
Once activated, the license is stored encrypted at ~/.xeroops/license.enc — you don't need license.json again for CLI operations. If you've lost your license.enc and need to re-activate on a new machine, email support@xeroops.com and we'll re-send your license file.
If your target AWS region differs from the AMI source region (us-east-2), both AMIs need to be copied. This takes 5–15 minutes depending on the region. It only happens once — subsequent runs in the same region use the local AMI copy. You'll see a progress message during the wait.
xeroops create rolls back automatically on failure — it attempts to delete any resources created before the failure point. Run xeroops status to check what state you're in, then run xeroops create again. If rollback failed and you have orphaned resources, run xeroops destroy --dry-run to see what's there, then xeroops destroy -confirm to clean up and start fresh.
Not without starting over. Region is baked into all resource IDs and ENI configurations. Run xeroops destroy -confirm to clean up, then xeroops init again with the new region. AMI copying to the new region will happen automatically.
EC2 instances launch in ~30–45 seconds. Services take another 30–60 seconds to start: cloud-init pulls config from S3, services start, and the deployment subscriber reinstalls your latest app wheels. Total: typically 60–90 seconds from xeroops deploy to a fully operational cluster.
Check the deployment subscriber logs on the app node:
# Connect via WireGuard first
ssh ubuntu@10.0.2.10
cat /var/log/xeroops/deployment_subscriber.logCommon causes: service name in the Redis message doesn't match the systemd unit name, or the wheel file path in S3 is wrong. Check service-ports.json in your S3 uploads bucket.
No. All nodes except openresty-lb are in a private subnet with no direct internet access. This is intentional — it's the air-gapped architecture. You must connect to WireGuard first, then SSH via the private IP (10.0.2.x). The SSH key is at ~/.xeroops/id_rsa.
After xeroops cleanup, your running cost is approximately:
| Resource | Cost |
|---|---|
| VPC, ENIs, Security Groups, IAM | $0.00 |
| 2 Elastic IPs (unassociated) | ~$7/month |
| S3 storage (logs, backups) | ~$3–8/month |
| EBS volumes (2 × db data) | ~$1–2/month |
Total idle cost: roughly $12–17/month. EC2 is the only significant cost and it's zero when stopped.
Connect via WireGuard first, then connect through HAProxy on the management node:
# Via HAProxy (recommended — same as app nodes use)
psql -h 10.0.2.20 -p 5432 -U postgres -d your_db
# Direct to primary (troubleshooting only)
psql -h 10.0.2.30 -p 5432 -U postgres -d your_dbFor DBeaver: your pgpass.conf is written automatically during xeroops init — DBeaver picks it up for passwordless connections.
SSH to db1 via WireGuard, then:
ssh ubuntu@10.0.2.30
sudo systemctl stop postgresql
# Restore to a point in time
sudo -u postgres wal-g backup-fetch /var/lib/postgresql/17/main LATEST
# Or a specific backup
sudo -u postgres wal-g backup-list
sudo -u postgres wal-g backup-fetch /var/lib/postgresql/17/main base_XXXXXXXXdb2 runs an automated restore test weekly — check /var/log/xeroops/walg_restore_test.log to confirm your backups are valid.
Point your domain's A record to the openresty-lb EIP (shown in xeroops status or in deploy output). Then connect via WireGuard and run certbot on openresty-lb:
ssh ubuntu@10.0.1.10
sudo certbot --nginx -d yourdomain.com -d api.yourdomain.com
Obtaining a new certificate...
Successfully deployed certificate for yourdomain.comCertbot auto-renewal runs via a systemd timer — no manual renewal needed. certbot and the renewal timer are pre-installed in the AMI.
xeroops deploy updates ~/.xeroops/xeroops.conf with the new WireGuard EIP automatically. In your WireGuard client, remove the old tunnel and re-import the updated config file. The client keys don't change between deploys — only the server endpoint IP.
Secrets follow a strict path:
- At rest:
~/.xeroops/state.enc— AES-256-GCM encrypted, key derived from your license - In transit to instances: S3 (
config/prod-credentials.env) — S3 server-side encryption (AES-256) - On instances:
/etc/environment— loaded at boot, readable only by root
No secrets ever go to Dassore servers. Everything lives in your AWS account.
The AWS user running xeroops needs: EC2 full access (for VPC, ENIs, instances, security groups), S3 full access (for buckets and objects), IAM (to create the EC2 instance role), and Route53 (optional, for DNS). We recommend using a dedicated IAM user with these permissions rather than your root account.
Still stuck?
Email us with your xeroops status output and a description of what you're seeing.