Sign in Subscribe
Tutorials

Configuring a Ceramic Node Using AWS

Joel Thorstensson

• 11 min read

In this guide you will learn how to configure and run a Ceramic node for development in AWS. AWS is not the only cloud provider you can use to run a Ceramic node, but we will cover the other major providers in a separate blog post. The general steps are going to be the same regardless of cloud provider, so you could adapt what you read here for your favorite cloud.

This post will cover running a Ceramic node in bundled mode, which is suitable for development and testing purposes.

Prerequisites

Before you can run a Ceramic node on AWS you’ll need a few things.

Preparing AWS for Ceramic

Once you have an AWS account you will need to configure a few things in AWS so that your Ceramic node can be accessed.

You will be creating a Linux EC2 instance, which you will then connect to using SSH. The recommended way to do this through AWS is to configure and use an Amazon EC2 Key Pair.

If you already have a key pair you wish to use you can head directly to the Configuring Security Groups section.

Creating a key pair

Step 1
From the AWS Management Console use the search bar to locate the EC2 Key Pair Feature page by typing in key pairs and selecting the corresponding EC2 Feature.

Step 2
Click the Create key pair button in the top right corner of the page.

Step 3
Configure the new key pair with the following options:

  • Name: ceramickeypair
  • Key pair type: RSA
  • Private key file format: .pem
  • If you are using a Windows machine select .ppk and make sure you have PuTTY installed
  • Tags: you do not need to add any tags, but you can if you’d like to organize your resources

Once you have those options selected click the Create key pair button.

You should be prompted to download the newly created key pair file. Save it somewhere that you will remember.

You will need this in a future step so don’t lose it!

You should now have a key pair populated in the management console as well as downloaded to your local machine.

This will be the private key used when connecting to the EC2 instance we will create using SSH.

Configuring Security Groups

The next thing you will need is an AWS Security Group for your soon-to-be-created EC2 instance. Security groups act as a virtual firewall for EC2 instances. To reach your Ceramic node you will need to have the proper ports configured in a security group.

Step 1
From the AWS Management Console use the search bar to locate the EC2 Security Groups Feature by typing security groups.

Step 2
You will most likely see a default security group. You can ignore this security group for now.

Click the Create security group button in the top right corner of the page.

Step 3
Configure the new security group with the following parameters:

Basic details

  • Security group name: ceramicservers
  • Description: allow access to Ceramic services
  • VPC: Leave as default unless you have a more complex AWS environment

Inbound rules

Rule 1:

  • Type: Custom TCP
  • Port range: 7007
  • Source: Anywhere-IPv4
  • Description: Ceramic port

Rule 2:

  • Type: SSH
  • Source: Anywhere-IPv4
  • Description: SSH port

Outbound Rules

  • Leave as default

Tags

  • Leave as default

Once you have filled in these configuration options click the Create security group button.

You should now see the newly-created security group in the management console.

Creating a Ceramic Node

Now that all of the AWS environment setup is complete it's time to begin building a Ceramic node in the cloud.

Creating an EC2 Instance For Ceramic

Step 1
From the AWS Management Console use the search bar to locate the EC2 Service by typing EC2 and selecting the corresponding service.

You should now be able to see the associated EC2 Resources that you set up in previous steps. If you are working from a new AWS environment you will see that there is 1 key pair and 2 security groups.

If you do not see these resources, ensure that you are viewing the proper region. Sometimes the AWS Management Console will display resources from different regions and can make it appear as though resources are missing when they are in fact in a different region.

Step 2
Below the Resources box you will see a Launch instance section. Click the orange Launch instance button in this section and select Launch instance from the drop down menu that appears.

Step 3
You are now ready to begin configuring an EC2 instance for your Ceramic node. This screen can seem a little daunting with all the options, so take extra care to configure options properly before launching your instance.

Improper configuration could result in charges to your AWS account. 3Box Labs and the Ceramic Network are not responsible for any charges you incur while working with cloud resources. Please double check all your work and understand the AWS billing process before proceeding.

Configure your EC2 instance with the following options:

Name and Tags

  • Name: Ceramic

Application and OS Images

  • AMI: Amazon Linux 2 AMI (HVM) - Kernel 5.10, SSD Volume Type (Free tier eligible)
  • Architecture: 64-bit (x86

Instance Type

  • Instance type: t2.micro (free tier eligible)

Key pair

  • Key pair name: ceramickeypair

Network Settings

  • Firewall: Select existing security group
  • Common security groups: ceramicservers

Configure Storage

  • 1x: 15gb
  • GiB: gp2

Advanced details

  • default

Once you have added these configuration details, set the Number of instances to 1 and click the orange Launch instance button located at the bottom of the Summary

Step 4
The Launch an instance page should now have a button that allows you to View all instances. Click the View all instances button to continue.

You will now see a new EC2 instance named Ceramic Server running in your environment.

In the next section you will connect to this instance and configure your Ceramic node.

Connecting to The Newly Created EC2 Instance

Connecting to this newly created EC2 instance will vary based on your operating system. If you are using Windows you will need an SSH client, such as PuTTY. If you are using Linux or MacOS you will be able to use the built-in SSH client located in the Terminal.

The instructions that follow will only cover the Linux and MacOS terminal. Once connected to the instance all commands and steps will be the same regardless of which operating system you are using.

Step 1
In the AWS Management Console select the Ceramic Server EC2 instance and click on the Connect button located near the top of the screen.

After clicking the Connect button select the SSH client tab to see the connection instructions for your instance. Your details will be different from what you see in the screenshot below since AWS populates this information dynamically.

Step 2
This step will guide you through the instructions located on the SSH client tab of the Connect to instance page.

Open your terminal and locate the key pair file you downloaded in Step 3 of the Preparing AWS for Ceramic section, it should be named ceramickeypari.pem if you followed along with the earlier steps.

This file may also have a .cer extension. This is perfectly fine and can be treated as a .pem file.

In this example the ceramickeypair.cer file is located in the Home directory of the logged in user.

When you download this file from AWS it downloads with improper permissions for use. If you try to use this file with your SSH client you will see an error explaining that the file has too many permissions to be used safely. Let’s fix that now by reducing the permissions granted to this key file.

In the terminal run the following command:

chmod 400 ceramickeypair.cer

There will be no output from this command, but if you inspect the permissions you should now see that this file is only able to be read by the owner. Learn more about file permissions.

Now that your file permissions are properly restricted, use your terminal to connect to your EC2 instance. The connection information can be found in the example at the bottom of the Connect to instance page you opened above in Step 1. Your details will differ from what you see below.

ssh -i "ceramickeypair.cer" ec2-user@ec2-54-215-186-11.us-west-1.compute.amazonaws.com

When prompted to accept the fingerprint, type the word yes to continue connecting to your instance.

You should now see the terminal change to reflect that you are connected to the EC2 instance.

You are now connected to your EC2 instance using SSH. Any commands you run inside this terminal will execute on the remote instance located on AWS.

Installing Ceramic Dependencies

Step 1
When you launch a fresh AWS instance, it’s always a good practice to start by updating the package manager. This Amazon Machine Image(AMI) uses yum as its package manager. To update the packages on the system run the update command as an administrator. In this case we will add the -y flag to skip being prompted if we are sure we want to apply the updates.

sudo yum update -y

There will be an overwhelming amount of information on the screen after you enter this command. The most important piece is at the end where the result of the command says complete and you have control of your prompt once more.

Step 2
One great thing about cloud computing is that the virtual machines provided for use are slim and often do not contain unnecessary software.

One downfall about cloud computing is that the virtual machines provided for use are slim and often do not contain the necessary software for our use case!

For a Ceramic node, your server will need NodeJS version 16 installed on it. The simplest way to manage different version of NodeJS is through the use of a tool called [Node Version Manager(NVM)].

To download and install NVM on your EC2 instance run the following command in the terminal:

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.1/install.sh | bash

It is important to note that NVM is frequently updated, you should always check the GitHub repository to ensure you are getting the most up-to-date version of NVM. This guide will NOT be updated as NVM versions change.

Once you see the information about what was added to the .bashrc file, NVM has been successfully installed.

However if you try to run NVM right now the terminal will display an error telling you the command nvm is not found.

To fix this error you need to “source” the .bashrc file to reload it into the current terminal session. Use the terminal to accomplish this. There will be no output from this command.

source .bashrc

Now if you type nvm into the terminal you should be greeted with the help text for this command.

nvm

Using NVM, install NodeJS Version 16.

nvm install 16

Your instance is now set up and ready to run Ceramic. Let’s get Ceramic running next!

Install and Run Ceramic

If you’ve made it this far then rejoice… the hard parts are over! Now you simply need to download and run Ceramic, and your AWS Ceramic Node will be fully accessible for your application.

Step 1
Use NPM to install the Ceramic daemon.

npm install -g @ceramicnetwork/cli

The amount of output from this command will be overwhelming; however, near the bottom of the output, you should see a message telling you that new packages have been added to your system.

Step 2
Run the Ceramic daemon to make this a usable Ceramic node.

ceramic daemon

Since you are running Ceramic in bundled mode, the output of this command will contain information about IPFS, to include peer discovery as well as Ceramic configuration information. When you see the message saying “Ceramic API running on 0.0.0.0:7007” you are ready to go.

Congratulations, you now have a Ceramic node running on AWS!

As you may have guessed, this is not an ideal setup. If you disconnect from this terminal session, shutdown the EC2 instance or perform many other tasks this process will terminate and your Ceramic node will be unreachable.

You may want to look into creating start-up scripts for your instance to ensure that the Ceramic daemon runs when the instance starts.

What’s next?

The only thing left is to connect to your instance using a Ceramic client.

Example using the Ceramic HTTP Client:

import CeramicClient from '@ceramicnetwork/http-client'
const API_URL = 'https://yourceramicnode.com' //AWS Public IPv4 info
const ceramic = new CeramicClient(API_URL)

Example using the Glaze CLI:

glaze config:set ceramic-url http://<AWS Public IPv4>:7007

Summary

You have now configured a Ceramic node in AWS that is accessible to anyone you share the IP Address or DNS address with.

It’s important to remember that Ceramic in bundled mode is intended for development purposes. Similarly to cloud providers other than AWS, future blog posts will guide you through setting up a node for production purposes.

Stay tuned for more Ceramic guides and tutorials. In the meantime, join us in the Ceramic forum for more direct help from our team and community!

Sign up for more like this.

Enter your email
Subscribe