npm package: @fulminate/deploy
Description: Easy to use CD tool written in Node.js and TypeScript
Author: Sergey Orlov
Latest version: 1.2.0

# 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

```typescript
// ./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:

```yml
# ./.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`.

```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:

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