deployer

Deployer is a relatively simple, yet powerful localhost CI/CD instrument. It allows you to:

• have your own actions and pipelines repositories (Actions Registry and Pipelines Registry) at your machine
• create actions and pipelines from TUI or using YAML configuration files
• configure actions for specific project
• satisfy requirements for your system to run pipelines
• check compatibility over actions and projects
• run actions and pipelines on remote hosts (you need to setup your remote access using SSH key, also you need to install deployer on remote host)
• use variables for commands from env-files and HashiCorp Vault KV2-storage
• run pipelines with different cache requirements in different build folders
• run pipelines inside containerized environments (Docker by default) with cache strategies
• run pipelines with watching the file system events and auto-restart
• run pipelines as Ansible Playbooks even without deployer on remote hosts
• export your pipelines as shell scripts, GitHub Actions or GitLab CI configurations
• store common content in Deployer's storage, add and patch additional files for build on the fly
• and share your project build/deploy settings very quickly and without any dependencies.

Migration guide

If you encounter problems after updating Deployer, especially after moving from 1.x to 2.x, please read Migration Guide.

Build

Well, the building process is very easy. You need to install Rust first:

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

After installation, execute this:

git clone https://github.com/impulse-sw/deployer.git
cd deployer
cargo install --path .

# if you already have Deployer installed
depl run install

That's it! Now you have /home/username/.cargo/bin/depl binary. Modify the PATH variable, if you need to.

Usage

All project configuration is stored in .depl/config.yaml file.

First of all, let's create a simple action.

depl new action

For example, let's name it UPX Compress. The short name will be upx, the version - 0.1.0.

The full YAML is:

info: upx@0.1.0
requirements:
  - type: exists_any
    paths:
      - /bin/upx
      - /usr/bin/upx
      - ~/.local/bin/upx
action:
  type: staged
  stage: build
  cmd: upx %af%
  placeholders:
    - "%af%"

If you're not familiar with UPX, consider visiting it's home page.

So, let's create a pipeline that will build the binary from the Rust code with preinstalled cargo-release@0.1.0 action and then compress this binary with upx@0.1.0.

depl new pipeline

The full YAML is:

title: pack
info: pack@0.1.0
default: true
artifacts:
  - from: target/release/my-app
    to: my-app
actions:
  - title: Build my app in release mode
    used: cargo-release@0.1.0
  - title: Compress my app
    used: upx@0.1.0

Note that you can change the inner content of actions inside Pipelines, and also can change the inner content of Pipelines and their actions if these Pipelines assigned to your project. The changes will not affect actions and Pipelines from Deployer's Registries.

You can view your actions and pipelines and get it in YAML by simple commands:

depl ls actions
depl ls pipelines

depl cat action upx@0.1.0
depl cat pipeline pack@0.1.0

And, of course, load actions and Pipelines from YAML files by:

depl new action -f {your config}

The next step is to init the project.

cd my-rust-project
depl init
depl edit .

You should add some actions and specify project variables that you'll use. For our example, add simple variable with target/release/my-app value. Also add cargo-release@0.1.0 and upx@0.1.0 actions from actions Registry. And not forget to add Cargo.lock file and target folder to cache files to prevent syncing project folder cache with run folder cache (without specifying this; see depl run --help for more).

After all you will get this .depl/config.yaml:

project_name: my-app
version: 7
ignore_files:
  - .git
cache_files:
  - Cargo.lock
  - target
variables:
  my-var:
    is_secret: false
    value:
      type: plain
      value: target/release/my-app
actions:
  - info: cargo-release@0.1.0
    tags:
      - rust
      - cargo
    requirements:
      - type: exists_any
        paths:
          - /bin/cargo
          - ~/.cargo/bin/cargo
    action:
      type: staged
      stage: build
      cmd: cargo build --release
  - info: upx@0.1.0
    requirements:
      - type: exists_any
        paths:
          - /bin/upx
          - /usr/bin/upx
          - ~/.local/bin/upx
    action:
      type: staged
      stage: build
      cmd: upx %af%
      placeholders:
        - "%af%"
pipelines:
  - title: pack
    desc: Got from `pack`.
    info: pack@0.1.0
    default: true
    artifacts:
      - from: target/release/my-app
        to: my-app
    actions:
      - title: Build my app in release mode
        used: cargo-release@0.1.0
      - title: Compress my app
        used: upx@0.1.0
        with:
          "%af%": my-var

Having only .depl/config.yaml inside your project's root, you can completely share your build/deploy configurations.

At the end, let's build the project!

depl run

# see the run options: you can share cache files and folders by symlinking or copying
depl run --help
depl run -fc

# or explicitly specify the project pipeline's short name - `build-and-compress`
depl run pack

# create pipeline with `Observe` action and start development server with auto-rebuild
depl watch build-and-deploy-devel

For other options, check:

depl run -h

Note

For more information, proceed to DOCS.md or run depl docs.