Campfire automates the creation and teardown of deploy previews for your application, and comes with an integrated feedback interface to make collaborative teamwork possible. We support serverless applications with a Dockerfile and provision resources on AWS.

To learn more, check out our case study.

Table of Contents

• Prerequisites
• Application Requirements
• Installation
• Configuring Campfire
• Using Campfire with your Application
• Commands
• FAQ

Prerequisites

• GitHub Account/Organization
• AWS CLI configured to your AWS account
• AWS IAM User with required permissions
• Node + NPM
• Domain Name

Application Requirements

• Contains a Dockerfile
• Has a serverless architecture
• Configured to run on port 8080
• Embedded Campfire SDK

Installation

$ npm install -g campfire-cli

Configuring Campfire

• Run campfire setup

• Input your AWS Region and domain for Campfire to use.

  • A configuration file will be created

• A server will be started at localhost on port 3000. You will be directed to register Campfire's GitHub App by visting localhost:3000 in your browser. You will be directed to GitHub where you will have to enter a unique name for the GitHub Application. This will be the name of the Campfire bot that posts comments on pull requests.

• Campfire will request an AWS SSL certificate. The certificate must be validated through DNS verification on your domain host.

  • Campfire will output 3 CNAME records that need to be added to your domain in order to verify the certificate. The setup process will not continue until the certificate is verified.
  • Keep your domain host window open for the last step.

• Once verified setup will proceed to provision all other AWS resources.

• Two additional CNAME records with hosts for \*.campfire-preview and campfire will be output. These records should also be added to your domain and be set to reference the application load balancer.

• It may take around 5 - 10 minutes for AWS to complete the stack build.

Using Campfire with your application

[!IMPORTANT]

GitHub App Installation

Make sure the Campfire GitHub App you registered during setup is installed and has access to the GitHub repository you are initializing. You have the option to install the GitHub App for all repositories or only selected repositories.

User/Organization Settings > Developer Settings > Github Apps > Edit > Install App

Embedding the Campfire SDK

In order for Campfire features to function properly, we require users to have the Campfire SDK embedded into their applications. There are two ways to embed the SDK:

1. Embed as an npm package

Install the Campfire SDK through your CLI:

npm install campfire-sdk

Create an instance of the Campfire SDK in a script:

import CampfireSDK from 'campfire-sdk'

new CampfireSDK()

2. Embed through a CDN link

Alternatively, import the SDK in a HTML file using our CDN:

<script type="module">
  import CampfireSDK from 'https://cdn.jsdelivr.net/npm/[email protected]/+esm'
  new CampfireSDK();
</script>

For React applications, create the instance within a useEffect hook:

import CampfireSDK from 'campfire-sdk'
import {useEffect} from 'react'

useEffect(() => {
  new CampfireSDK()
}, [])

Generating Workflow Files

• Navigate to the root of your project repository.

• Run campfire init

• Enter the name of your application. The name you provide will correspond to the cluster created in AWS Elastic Container Service.

• Campfire will build the workflow files for your project and place them in a new .github directory.

• Commit and push the directory to your GitHub repository.

• Add the AWS Access Keys that are output to your project's Github repository as secrets. See Environment Variables step 1 below for instructions on creating GitHub secrets.

• All future pull requests made will now generate Campfire deploy previews.

[!NOTE]

Environment Variables

If your application references environment variables that you don't want exposed in your GitHub repo, add them as GitHub Secrets.

1. Create GitHub Secrets

   • Navigate to the main page of your repository

   • Settings > Secrets > Actions > New repository secret

2. Add your environment variable(s)

   • Go to .github/workflows/create_preview.yml.

   • Add your environment variable as a GitHub Action env variable:

     env:
       MY_ENV_VAR: ${{ secrets.MY_ENV_VAR }}
       # ...

3. Reference in Task Definition

   • Go to .github/actions/deploy-preview/action.yml.

   • Go to line 52

     'environment': []

   • Add JSON for your environemnt variable key/value pair to the environment array. The 'value' corresponds to the name you gave your env variable in step 2.

     'environment': [{'name': 'MY_ENV_VAR', 'value': $MY_ENV_VAR}]

Commands

• campfire setup
• campfire init
• campfire list
• campfire destroy
• campfire help [COMMAND]

campfire setup

Provisions the AWS resources required for Campfire.

This command creates the underlying AWS infrastructure to support future deploy previews. This includes the following:

NOTE: The IAM User configured with your AWS CLI must have write permissions for the resources above.

See Configuring Campfire above for more details on the campfire setup process

See here for a complete list of resources provisioned.

See src/commands/setup.js

campfire init

Initializes Campfire in your project repository

Run it from the root directory of your repository and follow the prompts for each step of the initialization process.

See Using Campfire with your application above for more details on the campfire init process

See src/commands/init.js

campfire list

Lists all project repositories that have been initialized with Campfire. The names listed are all ECS Clusters that were created for each project during campfire init.

See src/commands/init.js

campfire destroy

Deletes all AWS resources provisioned from campfire setup and ECS clusters created in campfire init.

Run command after closing all open pull requests for initialized projects.

Users have the option to delete secrets created in AWS Secrets Manager.

• Deleting secrets will prevent your AWS from incurring charges for storing them.
• However, you will not be able to use Campfire (run setup) until these secrets are deleted. These secrets are scheduled to be deleted in seven days.

If you plan on using Campfire again in the near future, we advise not to delete the secrets.

See src/commands/destroy.js

campfire help [COMMAND]

Display usage and description for a Campfire command.

FAQ

How can I troubleshoot the setup command hanging at Provisioning AWS Resources?

Navigate to your AWS CloudFormation console. Click on the campfire stack created by the setup command and click on Detect Root Cause.

Any information or error logs relating to the CloudFormation stack can be found here.

If the stack creation rolled back due to Insufficient IAM permissions, it is likely that the IAM User configured with your AWS CLI does not have the specified permission. Navigate to the AWS IAM console and attach the appropriate permissions to your IAM User.

Why is the "Create Preview App" action failing when I make a pull request?

Make sure the Campfire GitHub App has been installed to the repository. See GitHub App Installation.

Verify that the repository contains your AWS Access Key and AWS Private Access Key as repository secrets. These credentials are output during campfire init.