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.

Deployment
Self-hosted
Area
Install

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 supplyExampleComes from
AWS regioneu-west-1Where Diakrin will run
AWS account id (recommended)123456789012aws sts get-caller-identity. The CLI refuses to run in any other account
Host namediakrin.example.comA name you control, on any DNS provider
Who owns DNSyou, a colleague, or Route 53 in this accountThey add two records in the first minutes
Audit retention365 daysCannot 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

sh
curl -fsSL https://diakrin.com/cli/install.sh | sh

You should see the installed version and a short list of next steps.

2. Set up your coding agents (optional)

sh
diakrin init

You 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:

sh
diakrin skills show diakrin-self-hosted-install

3. Write the settings

Create diakrin.env in an empty folder. These three lines are the only required settings; everything else has a default:

sh
cat > diakrin.env <<'EOF'
DIAKRIN_REGION=eu-west-1
DIAKRIN_HOST=diakrin.example.com
DIAKRIN_AUDIT_RETENTION_DAYS=365
EOF

You should have a diakrin.env file with three lines. Optional settings:

SettingUse it to
DIAKRIN_ACCOUNT_ID=<12-digit id>Refuse to run in the wrong AWS account
DIAKRIN_DNS=route53Create 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 noneChoose 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:

sh
diakrin self-hosted infra up --env diakrin.env --plan-only

You should see what is created, the estimated monthly cost and the audit retention.

After approval:

sh
diakrin self-hosted infra up --env diakrin.env --yes

You 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:

sh
diakrin self-hosted dns --env diakrin.env

You 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

sh
diakrin self-hosted deploy --env diakrin.env

You 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

sh
diakrin self-hosted doctor --env diakrin.env

You 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

  1. Open https://<host>/setup from any network.
  2. Enter the owner setup code and create the owner account.
  3. Point your GitHub App webhook at the address deploy printed (https://<host>/v1/self-hosted/github/webhook with the default exposure).
  4. 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 seeIt meansDo this
awaiting-dns (exit 7)A certificate record is missing at the DNS providerRun 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 approvalReview the plan, then add --yes
Any other errorEach error names its fixRead 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.

Next stepOperate your installation →