This Guidance demonstrates how to deploy and operate an InterPlanetary File System (IPFS) Cluster for Web2 and Web3 applications. With a highly available and serverless architecture, it can store and serve non-fungible token (NFT) assets, store Docker images, host a website, or distribute files across multiple regions. 

Architecture Diagram

Download the architecture diagram PDF 

Well-Architected Pillars

The AWS Well-Architected Framework helps you understand the pros and cons of the decisions you make when building systems in the cloud. The six pillars of the Framework allow you to learn architectural best practices for designing and operating reliable, secure, efficient, cost-effective, and sustainable systems. Using the AWS Well-Architected Tool, available at no charge in the AWS Management Console, you can review your workloads against these best practices by answering a set of questions for each pillar.

The architecture diagram above is an example of a Solution created with Well-Architected best practices in mind. To be fully Well-Architected, you should follow as many Well-Architected best practices as possible.

  • For the best performance of your workloads, deploy this Guidance with AWS CloudFormation or AWS Cloud Development Kit (AWS CDK) and have a test environment in which you can run a test cluster. Reflect this test environment with a special branch or tag in your code repository and have a 'develop' and 'main' branch.

    If you create a custom Docker image, track the Dockerfile changes in your code repository. Use AWS CodeBuild and AWS CodeDeploy to automate the Docker image builds and the deployment to production using triggers from your code repository.

    Implement application telemetry to closely monitor the usage and performances of your Fargate tasks and Amazon EFS volumes. Adjust capacity and plan for scale to deliver the most business value with the least amount of resources. 

    Read the Operational Excellence whitepaper 
  • Only the IPFS Swarm port 4001 is open to the Internet. It allows IPFS to communicate with the public IPFS network. The IPFS Gateway endpoint is publicly accessible. Authentication and authorization can be implemented using Lambda@Edge as mentioned in Deploying IPFS Cluster using AWS Fargate and Amazon EFS One Zone. The IPFS Cluster REST API endpoint is secured by Basic-Authentication which is the only authentication method supported by IPFS Cluster today. Both endpoints are behind a CloudFront distribution and enforce HTTPS access so credentials are encrypted in transit. CloudFront also protects your public endpoints against distributed denial-of-service (DDos) attacks.

    Because Amazon EFS is a network storage service, data is encrypted, backed up by default, and no data is lost if an IPFS node fails.

    Read the Security whitepaper 
  • This architecture is highly available by default. The CloudFormation stack deploys IPFS nodes in three availability zones (AZs). The network traffic is distributed to those three nodes using an Application Load balancer (ALB). It performs health checks on the nodes and takes them out of rotation if needed. The ALB is accessible only from CloudFront which fronts both the IPFS Gateway and IPFS Cluster REST API endpoints. IPFS nodes can be easily added or removed from the cluster. They will self-register against the main bootstrap node and join the cluster automatically, thereby making the cluster 'self-healing.'

    Prior to deploying the stack, increase the “Inbound or outbound rules per security group” quotas to 120. AMZ VPC quotas lists quotas, formerly referred to as limits, for Amazon Virtual Private Cloud (Amazon VPC) resources. 

    Amazon ECS manages the services in which the IPFS nodes run. It monitors all containers by performing regular health checks. If a container is unresponsive, Amazon ECS will restart the task.

    Logs are captured in Amazon CloudWatch. Each node logs both IPFS and IPFS Cluster container logs in separate log groups. Default Fargate and Amazon EFS metrics are also available in CloudWatch and CloudWatch alarms can be used to trigger scaling events.

    Changes to the cluster configuration is done entirely through Docker images. New images must be built to change the configuration and the cluster must be redeployed to use them. Create a new Amazon ECS Task Definition to point to the latest Docker image or specific tag then redeploy the cluster. You may need to force redeploy the cluster if you update your Docker image.

    Data is distributed by IPFS Cluster across three Amazon EFS volumes in three different AZs. Also, Amazon EFS backs up data by default. The compute layer is stateless as the IPFS files and configurations are stored in Amazon EFS.

    Read the Reliability whitepaper 
  • Fargate allows for multiple CPU and memory configurations to support different needs. Amazon EFS can support most common use cases but has throughput limitations compared to Amazon Elastic Block Chain Store (Amazon EBS), as mentioned in Deploying IPFS Cluster using AWS Fargate and Amazon EFS One Zone

    CloudFront caches IPFS contents at the edge to provide high performance and low latency. It also relieves the IPFS Gateways and uses the AWS network backbone to connect to the IPFS Gateway nodes.

    Read the Performance Efficiency whitepaper 
  • This Guidance is fully serverless and uses managed services. There is very little operational work needed to operate this architecture. The service costs to consider are:

    • Fargate: Static cost based on the number of IPFS node you run. 
    • Amazon EFS: Variable cost based on the amount stored, and the amount of Reads and Writes.
    • Data transfer: Variable cost based on the volume served through IPFS network and IPFS Gateway. 

    For further cost optimization, monitor the network usage of your nodes closely. IPFS can cause high network usage when it produces a lot of input/output operations per second (IOPS). 

    To reduce network traffic, some nodes can be restricted from having Internet access. Those nodes would talk exclusively to bootstrap the nodes on the internal network. The bootstrap nodes would have the Internet and would proxy all calls to the Internet. To do this, create a custom Docker image as mentioned in Deploying IPFS Cluster using AWS Fargate and Amazon EFS One Zone.

    Read the Cost Optimization whitepaper 
  • Fargate is managed and operated by AWS. AWS containers only consume the CPU and memory that AWS configures. AWS can adjust the nodes to keep waste to a minimum. Managed services and containers are more efficient than running on Amazon Elastic Compute Cloud (Amazon EC2).

    Read the Sustainability whitepaper 

Implementation Resources

A detailed guide is provided to experiment and use within your AWS account. Each stage of building the Guidance, including deployment, usage, and cleanup, is examined to prepare it for deployment.

The sample code is a starting point. It is industry validated, prescriptive but not definitive, and a peek under the hood to help you begin.


Deploying IPFS Cluster using AWS Fargate and Amazon EFS One Zone

This post demonstrates how to deploy a highly available and serverless IPFS Cluster using AWS Fargate and Amazon EFS One Zone. 


The sample code; software libraries; command line tools; proofs of concept; templates; or other related technology (including any of the foregoing that are provided by our personnel) is provided to you as AWS Content under the AWS Customer Agreement, or the relevant written agreement between you and AWS (whichever applies). You should not use this AWS Content in your production accounts, or on production or other critical data. You are responsible for testing, securing, and optimizing the AWS Content, such as sample code, as appropriate for production grade use based on your specific quality control practices and standards. Deploying AWS Content may incur AWS charges for creating or using AWS chargeable resources, such as running Amazon EC2 instances or using Amazon S3 storage.