Fulminate Deploy

@fulminate/deploy is an easy to use package that allows your server to listen to hooks incoming from your VCS and execute automated code update for your projects.

REMEMBER You need to set up SSH keys yourself for your server if you use private repositories.

Installation

mkdir deploy

cd deploy

npm init -y

npm i --save @fulminate/deploy

Usage

// ./index.ts
import { deploy, server } from '@fulminate/deploy';

deploy;
console.log(`Server running on port ${server.appOptions.port}`);

When you run this script, you will get an Express application running.

Setting Up

Create a .fulminate directory in the root of your project and inside of it, provide the deployment options in an app.yml file:

# ./.fulminate/app.yml

# Fulminate Framework specific options
# @see https://fulminate-js.github.io/
bcrypt:
  enabled: false
slackOptions:
  enabled: false
  channel: 'general'
  apiKey: 'key'
domain: 'example.com'
port: 3000
viewOptions:
  enabled: false

# Deployment options
deployOptions:
  # If you disable deployment, server will throw AccessDeniedError on attending the hook route
  enabled: true

  # Route that will wait for VCS hook
  # You need to provide your domain plus this route as your VCS hook URL
  route: /deploy/api/v1/hook

  # Projects living on your current server
  projects:
    # Project name. This value is used to provide deployment options correctly
    # You need to provide this exact value at the end of your VCS hook URL
    # @example https://fulminate.js/deploy/api/v1/hook/main
    main:
      # Git branch to checkout
      branch: master

      # Git repository
      repository: git@github.com:fulminate-js/bootstrap.git

      # Path to the project that needs to be redeployed
      projectDir: ~/Documents/testing

      # The name of the folder that contains the build. Defaults to `./` meaning the project itself
      # will be copied to the projectDir folder. It is defined relatively to the cloned project.
      buildFolderName: build

      # List of scripts to be executed before copying cloned files to your project directory
      # NOTE: these scripts are executed inside the temporary directory, i.e. the cloned project
      beforeCopyScripts:
        - npm i
        - npm run build
      # You can put a list of files to be copied to your project directory
      filesToCopy:
          # Location of the file that needs to be copied
        - location: ./app.yml
          # Path where the file should be put
          # $PROJECT_DIR will be replaced with `projectDir` given above
          savingPath: $PROJECT_DIR/.fulminate/
      # List of scripts to be executed after copying the files to the project directory
      # NOTE: these scripts are executed inside the project folder
      scripts:
        - npm i --only=production
        - pm2 reload main

Adding files to copy

In the root folder of the deployer, let's create the file listed in the filesToCopy property of our app.yml.

# ./app.yml

port: 3001

Integration

Open settings of your project, create a hook to the route from the ./.fulminate/app.yml and set it to be executed on pipeline. Fulminate Deploy will only work on successful build (will be an option in a later release).

Example hook URL: https://test.com/deploy/api/v1/hook/main

Workflow

You push code to VCS
Pipeline is executed and sends a hook to Fulminate Deploy
If the pipeline was successful:

FD creates a backup copy of the current state of your project
FD clones the repository to a temporary directory
FD executes all the beforeCopyScripts
FD copies the contents of the temporary directory to your project directory
FD executes all the scripts
FD writes a log to ./history.json file