Skip to content

README.md

Latest commit

 

History

History
128 lines (102 loc) · 6.16 KB

README.md

File metadata and controls

128 lines (102 loc) · 6.16 KB

SimpleNS Terraform AWS Template

This is a standalone Terraform template to quickly provision and deploy an instance of SimpleNS (Simple Notification System) on an AWS EC2 instance.

The template provisions an EC2 instance running Amazon Linux 2023, configuring the security groups to only allow traffic on ports 22 (SSH), 80 (HTTP) and 443 (HTTPS). It utilizes a install.sh script to automatically install Docker, Docker Compose, Node.js, and use the @simplens/onboard CLI tool to fully bootstrap the entire SimpleNS stack including its infrastructure (MongoDB, Redis, Kafka, etc). You can customize the onboard command in the install.sh script. To know more about the available cli options in @simplens/onboard tool, run npx @simplens/onboard@latest --help.

Prerequisites

  1. AWS Account: An AWS account with permissions to manage EC2, VPCs, and Security Groups.
  2. AWS CLI Setup: Make sure AWS CLI is installed and configured with appropriate credentials on your local machine. (See AWS Credentials Setup below).
  3. Terraform: Make sure Terraform (>= 1.0.0) is installed.
  4. AWS Key Pair: An existing SSH key pair in your target AWS region to access the EC2 instance.

AWS Credentials Setup

To allow Terraform to provision resources, you need to configure the AWS CLI with programmatic access credentials.

  1. Create an IAM User:

    • Log in to the AWS Management Console.
    • Navigate to IAM > Users and click Create user.
    • Provide a username (e.g., terraform-provisioner) and click Next.

  2. Attach Permissions:

    • Select Attach policies directly.
    • Attach the AdministratorAccess policy (or create a custom policy with least privilege for EC2, VPC, and Security Group management).
    • Click Next, then Create user.

  3. Generate Access Keys:

    • Click on the newly created user and navigate to the Security credentials tab.
    • Scroll down to Access keys and click Create access key.
    • Select Command Line Interface (CLI), check the confirmation box, and click Next.
    • Copy the Access key ID and Secret access key. (Note: The secret key will only be shown once, so store it securely).

  4. Configure AWS CLI:

    • Open your terminal and run: 
      aws configure
    • Paste your Access key ID and Secret access key when prompted.
    • Enter your preferred default region (e.g., us-east-1) and default output format (e.g., json).

Usage

1. Variables Configuration

Customize the deployment by changing the variables in the terraform.tfvars file (create it if it doesn't exist) or by passing them directly into the Terraform CLI context.

Create a terraform.tfvars file inside this directory:

aws_region    = "us-east-1"
instance_type = "t3.medium"
instance_name = "simplens-server"
key_pair_name = "your-aws-key-pair-name"

(Make sure to replace your-aws-key-pair-name with the actual name of your key pair existing in AWS console).

2. Deploy infrastructure

Initialize the working directory containing Terraform configuration files:

terraform init

Preview the changes to your infrastructure:

terraform plan

Execute the actions proposed by the Terraform plan:

terraform apply

Type yes when prompted to confirm the execution.

3. Accessing the Application

Once the terraform apply finishes successfully, it will output the necessary connection parameters in your console. For example:

Outputs:

dashboard_url = "http://203.0.113.12/dashboard"
instance_id = "i-0abcd1234efgh5678"
public_ip = "203.0.113.12"
ssh_connection_string = "ssh -i /path/to/your-aws-key-pair-name.pem ec2-user@203.0.113.12"

Please note that the install.sh script will require a few minutes to fully set up the host, pull Docker images, and start the application. After approximately 5-10 minutes, your SimpleNS dashboard will be ready and accessible at the emitted dashboard_url.

To tail the initialization logs, you can SSH into the instance and run:

sudo tail -f /var/log/cloud-init-output.log

4. Logging into the Dashboard

To successfully log in to your SimpleNS dashboard, the session cookies must be securely stored by your browser. You have two options to achieve this:

Option A (Recommended): Setup HTTPS / SSL Configure a domain name and set up an SSL certificate (e.g., using Let's Encrypt or AWS ACM/ALB) in front of your instance so it can be accessed securely via https://.

Option B (For Development Only): Disable Secure Cookies If you want to access the dashboard purely over HTTP using the raw IP address, you must configure SimpleNS to run in development mode so that it doesn't enforce secure cookies.

  1. SSH into the instance.
  2. Navigate to your installation directory (e.g., /opt/simplens).
  3. Open the .env file and change NODE_ENV=production to NODE_ENV=development.
  4. Restart your containers (docker compose down && docker compose up -d).

5. Default Admin Credentials

When the @simplens/onboard script bootstraps your environment, it automatically generates a default admin password.

  1. SSH into your newly created instance.
  2. Check the .env file in the installation directory for your credentials: 
    cat /opt/simplens/.env | grep ADMIN_PASSWORD
  3. Use admin as the username along with the found password to access the SimpleNS dashboard.
  4. Important: You can change this password at any time by updating the ADMIN_PASSWORD variable in the .env file and restarting the containers (docker compose up -d).

Security Group Ports

By default, the following inbound rules are permitted:

  • Port 22: SSH remote access
  • Port 80: HTTP web access (Nginx reverse proxy, dashboard setup)
  • Port 443: HTTPS web access

Currently, the auto-provisioning installs and sets up port 80 by default.

Cleanup

If you wish to terminate the provisioned resources, simply run:

terraform destroy

Type yes when prompted to confirm the deletion. Note that this action is irreversible and will delete the EC2 instance along with its attached EBS volume containing the application data.