Custom Domains

Connect your own domain to your sota.io project with automatic HTTPS.

Overview

Every project on sota.io gets a default URL at {slug}.sota.io with automatic HTTPS. You can also add up to 5 custom domains per project, each with automatic SSL certificates via Let's Encrypt.

Custom domains support both apex domains (example.com) and subdomains (app.example.com).

Prerequisites

Your project must have at least one successful deployment.
You need access to DNS settings at your domain registrar.

Adding a Domain

Via Dashboard

Go to your project in the Dashboard.
Scroll down to the Custom Domains section.
Enter your domain (e.g., app.example.com).
Click Add Domain.

The dashboard will display DNS instructions for your domain.

Via API

curl -X POST https://api.sota.io/v1/projects/550e8400-.../domains \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"domain": "app.example.com"}'

The response includes dns_instructions with the exact DNS record you need to add.

DNS Configuration

After adding your domain, configure DNS at your registrar:

Apex Domains (example.com)

Add an A record pointing to the sota.io edge proxy:

Type	Name	Value
A	@	23.88.45.28

Subdomains (app.example.com)

Add a CNAME record pointing to your project's sota.io URL:

Type	Name	Value
CNAME	app	your-project-slug.sota.io

Replace your-project-slug with your actual project slug (visible in the dashboard or via API).

Note: DNS propagation can take up to 48 hours. sota.io checks automatically every 60 seconds until verification succeeds.

SSL Certificates

SSL certificates are provisioned automatically via Let's Encrypt HTTP-01 challenge:

You add your domain and configure DNS.
sota.io detects the correct DNS record.
A Let's Encrypt certificate is requested and provisioned.
Your domain is live with HTTPS -- no manual action needed.

Certificates are renewed automatically before expiration.

Domain Statuses

Status	Meaning
Pending	Waiting for DNS verification. Add the DNS record shown in the dashboard.
Verified	DNS record is correct. SSL certificate is being provisioned.
Active	Domain is live with HTTPS. Traffic is being routed.
Error	Something went wrong. Check the error message for details.

Limits

Maximum 5 custom domains per project.
Both apex domains and subdomains are supported.
Wildcard domains are not supported.
You cannot add platform domains (*.sota.io) as custom domains.

Troubleshooting

Problem	Solution
Domain stuck on "Pending"	DNS changes can take up to 48 hours to propagate. Verify your DNS record is correct using `dig` or an online DNS checker.
Wrong IP in A record	The A record must point to `23.88.45.28` (the edge proxy). Do not use other IPs.
CNAME vs A confusion	Use an A record for apex domains (example.com). Use a CNAME for subdomains (app.example.com).
SSL certificate pending	The certificate is provisioned after DNS verification passes. This usually takes a few minutes.
"Domain already exists" error	The domain is already added to another project. Remove it first before adding to a different project.