Code deployment¶

Direct git deployments¶

Only for Drupal and WP

Direct git deployment is available only for Drupal and WordPress stacks and their forks

You can connect your git repository to Wodby and use it as a codebase source for your applications. On code deployment we will perform pull from the target branch and run post-deployment scripts (if enabled).

Additionally, you can run deployment automatically every time you push code to a git branch (all instances using this branch will be deployed):

Configure git hooks for your git repository
Navigate to Instance > Deployment > Settings and check Automatic deploy option

For details instructions how to connect a repository and configure hooks see the following articles:

CI/CD¶

Sometimes direct git integration may not be enough for a few reasons:

Build stage is a must-have for repositories with dependencies (e.g. npm, composer)
You need to run tests
Direct git deployment cannot be used for custom stacks and cluster deployments
With CI/CD you have build artifacts like docker images that you can download locally

Via third-party CI¶

You can set up CI/CD workflow for your application by integrating Wodby with third-party CI tools. Build can be performed on any CI tools with Wodby CLI.

Big picture:

Deploy an app based on a managed stack that supports CI deployments or custom stack with at least one service having deployment.type=ci
Get Wodby CLI tool or its docker image
Initialize the build by providing your Wodby API key and UUID of your app instance
Build images with your codebase. Images will be based on the images from your stack
Push (release) images to a private docker registry we provide you (or any other registry)
Deploy the build (a set of images) to your app instance

Do not store your Wodby API key in git repository

Do not share your personal Wodby API key. Do not store it in git repository, instead add it as a secret environment variable in your CI settings.

Wodby CLI¶

VM-based builds over docker-in-docker

If your CI tool can run builds both in Docker and Virtual Machine (docker daemon must be available) we recommend using the latter because it's faster

You can install the latest stable Wodby CLI (Linux amd64) tool during the build like this:

wget -qO- https://api.wodby.com/api/v1/get/cli | sh

If you want to install it locally for other systems such as macOS or Windows, or install a specific version follow the instructions at https://github.com/wodby/wodby-cli

Or you can use wodby/wodby-cli docker image if your CI supports only docker-based builds

Init¶

wodby ci init [INSTANCE UUID]

This command will gather build information about your instance such as services (images) that can be built and private docker registry credentials. All builds must start with the init. To perform this step you must have your Wodby API key exported as $WODBY_API_KEY or provided via --api-key. Make sure the key is secured and not exposed to public.

Build¶

Services available during the build

If you're building a managed stack, the list of services eligible for the build is hardcoded and you can find it in a stack documentation. If you're building a custom stack, all services that have deployment.type=ci will be available

During the build stage you can prepare your codebase for the build by running wodby ci run which is basically a wrapper of docker run.

You can either specify a docker image that runs a command:

wodby ci run -i wodby/node -- yarn install
wodby ci run -i wodby/node -p path/to/frontend -- yarn install

Or specify a service name from your stack, the image of your current stack version will be used:

wodby ci run -s backend -- composer install -n

You can use bind mounts on libraries cache directories to utilize caching capabilities of your CI tool (.travis.yml example):

cache:
  directories:
    - /home/travis/.composer

script:
  - wodby ci run -v $HOME/.composer:/home/wodby/.composer -s php -- composer install -n

In some environments like CircleCI (where uid is different from 1000) you also need to fix your cache directory permissions before mounting them in wodby ci run command:

- run: wodby ci run -v $HOME/.composer:/home/wodby/.composer --user root -- chown -R 1000:1000 /home/wodby/.composer

If you need to access private repositories you should add a checkout ssh key to your environment (please refer to your CI provider documentation), then mount the key and .known_hosts file (to avoid interactive dialogues), example for CircleCI:

- run: 
    name: Install composer dependencies with private packages
    command: wodby ci run \
        -v /home/circleci/.ssh/known_hosts:/home/wodby/.ssh/known_hosts \
        -v /home/circleci/.ssh/id_rsa_[your-checkout-key-fingerprint]:/home/wodby/.ssh/id_rsa \
        -v $HOME/.composer/cache:/home/wodby/.composer/cache \
        -s php -- composer install -n

Once the codebase is ready you can run the build via wodby ci build which is a wrapper of docker build. By default the build command builds a new image based on the image of a service you specified, and copies codebase (contents of the current directory, same as --from \.) to service's image default working directory:

# Build all ci services' images
wodby ci build 
# Same thing
wodby ci build --from \.
# Build php service image 
wodby ci build php
# Build all images of services starting with node-
wodby ci build node-*
# Build php service image with the contents from ./build directory
wodby ci build php --from ./build
# Build node service image with the contents from ./build directory to /usr/src/app directory inside node image 
wodby ci build node --from ./build --to /usr/src/app

Or you can build from your own Dockerfile:

wodby ci build --dockerfile /path/to/my/Dockerfile

If you're using custom Dockerfile make sure it starts with the following lines to make sure it will be based on the image from your stack:

ARG WODBY_BASE_IMAGE
FROM ${WODBY_BASE_IMAGE}

By default we build images with the name (tag) of a private docker registry we provide. But you can use your own registry:

wodby ci build -t my-private-docker-hub/repository

Release¶

Docker registry

Wodby provides a private docker registry registry.wodby.com which used by default. You can use custom docker registry during the build but if it's a private one make sure to add the appropriate docker registry integration so servers where you deploy instances can access your images.

How to download images?

Once you deployed your first build you can find images' URLs on Instance > Stack page. You can get those images locally by running docker login registry.wodby.com and entering your Wodby user's email/password.

Once images are built, you can push them to a docker registry:

# Push all images to the default docker registry 
wodby ci release
# Push images of specific services 
wodby ci release php node
# Push to a custom docker registry
wodby ci release -t my-private-docker-hub/repository
# Additionally push with the tag of the current git branch name 
wodby ci release -t my-private-docker-hub/repository -b

Deploy¶

# Deploy all services from the default docker registry
wodby ci deploy
# Deploy specific services
wodby ci deploy php crond
# Deploy all services from a custom docker registry
wodby ci deploy -t my-private-docker-hub/repository

Examples¶

You can find build examples for different CI services such as CircleCI, TravisCI, BitBucket pipelines and custom shell scripts at https://github.com/wodby/wodby-ci