ipfs-cluster-aws icon indicating copy to clipboard operation
ipfs-cluster-aws copied to clipboard

ipfs-cluster on AWS

Deploys a multi-region DNS-balanced TLS-enabled network of ipfs-cluster nodes running on NixOS on AWS EC2 cloud servers using Terraform.

First, Install nix, clone this repo and cd in.

Zero to Hero

Set up or choose an existing, public Route53 Hosted zone to use for subdomains.

Get or create an AWS access key with appropriate permissions.

Configure credentials and default region for Terraform's AWS provider. For example, using environment variables:

export AWS_ACCESS_KEY_ID="..."
export AWS_SECRET_ACCESS_KEY="..."
export AWS_DEFAULT_REGION="us-west-2"

Set Terraform imput variable values, for example by copying terraform.tfvars.example to terraform.tfvars and editing it. See inputs.tf for all variables and documentation. If you do not set variables, Terraform will ask you for the required ones on every run.

Start the deployment:

nix-shell --run 'terraform apply'

Read the plan and accept it if you are satisfied. When the deployment is done, read the outputs. Access the gateway at https://your-environment-ipfs-cluster.your-domain/ .

Connect to a server and run some commands:

ssh root@<your-environment>-ipfs-cluster-us-east-1-node0.<your-domain> -i SECRET/private_key 'ipfs-cluster-ctl peers ls'

When you're done, don't forget to destroy the cloud resources so as not to waste power and money:

nix-shell --run 'terraform destroy'

Develop

Start the deployment shell to see a list of available commands:

nix-shell

What? Where?

  • infrastructure
    • main.tf defines global cloud resources
    • regions.tf instantiates resources per region
    • ipfs-cluster-aws-region/main.tf defines per-region AWS cloud resources (vpc, sg, acl, ec2, ebs, r53, etc.), ie. a network of cloud servers running NixOS
  • operating sysem configuration
    • nixos/ipfs-cluster-aws.nix is a NixOS profile for running an ipfs-cluster node on AWS EC2 with required services and configuration
    • nixos/ipfs-cluster.nix is a NixOS module for configuring and running the ipfs-cluster service
  • deployment environment
    • shell.nix is loaded by nix-shell and includes dependencies and scripts used for infrastructure deployment
  • nix/ package definitions and dependencies
    • sources.json locations and hashes managed by niv

Security

The Terraform state terraform.tfstate contains sensitive data such as the cluster secret. The state should be encrypted and may be stored remotely.

If you don't specify a public_key variable, a private key without a passphrase is generated and saved to SECRET/private_key. For production use, generate a key with passphrase (stored in your keychain), specify this variable and let ssh find the private key, eg. via .ssh/config.