Self-hosted (AWS)
Install self-hosted Diakrin
Install Diakrin into your AWS account with the CLI: infrastructure, DNS, deploy and owner setup, with the expected result of every command.
One person installs Diakrin into your AWS account from a computer signed in to AWS, using four commands and about 60 minutes. No installer host is needed.
Before you start
| You supply | Example | Comes from |
|---|---|---|
| AWS region | eu-west-1 | Where Diakrin will run |
| AWS account id (recommended) | 123456789012 | aws sts get-caller-identity. The CLI refuses to run in any other account |
| Host name | diakrin.example.com | A name you control, on any DNS provider |
| Who owns DNS | you, a colleague, or Route 53 in this account | They add two records in the first minutes |
| Audit retention | 365 days | Cannot be shortened after the first install |
The full list of requirements (AWS CLI v2, Fargate quota, GitHub organization admin) is on Prerequisites. A license file from Diakrin is optional: see License.
1. Install the CLI
curl -fsSL https://diakrin.com/cli/install.sh | shYou should see the installed version and a short list of next steps.
2. Set up your coding agents (optional)
diakrin initYou should see the agent skills installed for the coding agents on this computer. To use one in an agent that is already running, print it into the session instead of restarting the agent:
diakrin skills show diakrin-self-hosted-install3. Write the settings
Create diakrin.env in an empty folder. These three lines are the only required settings; everything else has a default:
cat > diakrin.env <<'EOF'
DIAKRIN_REGION=eu-west-1
DIAKRIN_HOST=diakrin.example.com
DIAKRIN_AUDIT_RETENTION_DAYS=365
EOFYou should have a diakrin.env file with three lines. Optional settings:
| Setting | Use it to |
|---|---|
DIAKRIN_ACCOUNT_ID=<12-digit id> | Refuse to run in the wrong AWS account |
DIAKRIN_DNS=route53 | Create the DNS records automatically when the zone is in this account |
DIAKRIN_ROUTE53_ZONE_ID=<zone id> | Pick a specific Route 53 zone |
DIAKRIN_EXPOSE=cloudfront or none | Choose how people reach Diakrin. See Existing infrastructure and exposure |
DIAKRIN_INSTALLATION=<id> | Name the installation (3 to 24 lowercase letters, digits or hyphens) |
DIAKRIN_VERSION=<X.Y.Z> | Pin a release. The default is the latest stable release |
DIAKRIN_LICENSE_FILE=<path> | Use a license file from Diakrin. See License |
AWS_PROFILE=<name> | Use a named AWS CLI profile |
Settings to reuse your own VPC, database, cluster, certificate or DNS are listed on Existing infrastructure and exposure. Never put a database URL, key or token in this file; the CLI refuses it. diakrin --json schema self-hosted deploy lists every setting.
4. Create the infrastructure
First look at the plan. It changes nothing:
diakrin self-hosted infra up --env diakrin.env --plan-onlyYou should see what is created, the estimated monthly cost and the audit retention.
After approval:
diakrin self-hosted infra up --env diakrin.env --yesYou should see steps run for 15 to 30 minutes and the command end with the target saved. If it stops, run the same command again; it resumes.
5. Add the DNS records
Skip this step if you set DIAKRIN_DNS=route53 and the zone is in this account: nothing is manual.
Within the first minutes of infra up, before the long part of the install, the CLI prints the certificate validation record, saves it to diakrin-dns.txt next to diakrin.env, and prints the host record as soon as its target is known (the CloudFront domain by default). Give both to whoever owns DNS now. The install keeps going; only the HTTPS listener and the CloudFront host name wait for the certificate. On Cloudflare, set the records to DNS only.
Anyone with the settings file and AWS access can see which records are still needed, and whether each one resolves, from any computer:
diakrin self-hosted dns --env diakrin.envYou should see each record with resolves: yes once it is in place. If the command waited out its 30 minutes before the records existed, it exits with code 7 and awaiting-dns: add the records, then run the same infra up command again.
6. Deploy Diakrin
diakrin self-hosted deploy --env diakrin.envYou should see the images copied by digest, the database migrations run inside the VPC, and three services running. It takes up to 30 minutes; if it is interrupted, run the same command again. It ends with the console URL and a command that reads the one-time owner setup code.
7. Check it
diakrin self-hosted doctor --env diakrin.envYou should see every check pass: services, certificates, the CloudFront distribution with its host name and firewall, the console and the webhook route as seen from the internet, and egress, database TLS and GitHub from inside the VPC.
8. Finish setup in the browser
- Open
https://<host>/setupfrom any network. - Enter the owner setup code and create the owner account.
- Point your GitHub App webhook at the address
deployprinted (https://<host>/v1/self-hosted/github/webhookwith the default exposure). - Add your license file in the console's License step if you have not already. See License.
You should see the console with the setup stages. Finish them in Get started.
If it fails
| You see | It means | Do this |
|---|---|---|
awaiting-dns (exit 7) | A certificate record is missing at the DNS provider | Run diakrin self-hosted dns --env diakrin.env, add what it lists, then run infra up again |
CONFIRMATION_REQUIRED (exit 2) | The command needs a person's approval | Review the plan, then add --yes |
| Any other error | Each error names its fix | Read error.nextAction (or the line starting with an arrow) and run the same command again; every step is resumable |
More errors and fixes are on Troubleshooting.
Next
Learn the day-to-day commands on Operate your installation.