Neoteric Plumbing Mishap

    octoblu

    1.0.4 • Public • Published

    octoblu

    Run your own Octobu stack in Docker Swarm.

    WARNING!

    This documentation is incomplete, if you run into any trouble, please create an issue or submit a pull request. Thank you!

    Prerequisites

    • Docker >= 17.09.0-ce
    • Node.js >= 8.0

    Installation

    yarn global add octoblu

    or

    npm install --global octoblu

    Local Development

    Runing a local development stack is similar to a production cluster, however there are some special considerations to make to enable a local stack.

    These instructions assume you are developing on localhost. The domain localtest.me can be used to access services locally without setting up your own DNS or hosts (e.g. meshblu-http.localtest.me) .

    Bootstrap

    Octoblu requires some devices to exist in Meshblu before certain services will run. Creating the bootstrap stack will help to create these devices and provide some defaults to add to your dev stack. Redis and Mongo will be started as part of this stack and will persist data using a docker volume. Removing this docker volume will erase all data and you will need to bootstrap again.

    mkdir dev
    cp examples/dev/defaults.env dev/defaults.env
    octoblu-stack-generator --output dev --stack bootstrap-development --init --no-constraints
    octoblu-stack-generator --output dev --stack bootstrap-development --no-constraints
    cd dev
    docker stack deploy --compose-file ./docker-compose.yml octoblu

    Once services are running, you'll need to curl the bootstrap service to generate the appropriate devices.

    cd dev
    curl -X POST http://bootstrap.localtest.me/bootstrap >> defaults.env
    cd ..
    octoblu-stack-generator --output dev --stack octoblu-development --init --no-constraints
    octoblu-stack-generator --output dev --stack octoblu-development --no-constraints
    cd dev
    docker stack deploy -c ./docker-compose.yml octoblu

    Production Cluster

    Prequisites

    • Mongodb >= 3.0
    • Redis >= 3.0

    This step will create a small Octoblu production cluster. Setting up MongoDB and Redis is outide the scope of this document.

    These instructions assume you have a domain available and will setup a wildcard DNS entry to point to your docker swarm. It also assumes you will use let's encrypt for ssl certs. The examples provided are configured for Digital Ocean as a DNS provider, for alternatives see traefik docs.

    Bootstrap

    Octoblu requires some devices to exist in Meshblu before certain services will run. Creating the bootstrap stack will help to create these devices and provide some defaults to add to your dev stack. Redis and Mongo will be started as part of this stack and will persist data using a docker volume. Removing this docker volume will erase all data and you will need to bootstrap again.

    mkdir prod 
    cp examples/prod/defaults.env prod/defaults.env
    cp -r examples/prod/overrides prod/overrides
    # Edit prod/overrides/stacks/traefik.yml and add your domain 
    # Edit prod/overrides/templates/traefik/environment.json and add your Digital Ocean credentials 
    octoblu-stack-generator --output prod --stack bootstrap --init --overrides
    # Edit prod/defaults.env and set MONGODB_URI and REDIS_URI to the correct URLs 
    octoblu-stack-generator --output prod --stack bootstrap --overrides
    cd prod
    docker stack deploy --compose-file ./docker-compose.yml octoblu

    Once services are running, you'll need to curl the bootstrap service to generate the appropriate devices.

    cd prod
    curl -X POST http://bootstrap.{your.domain}/bootstrap >> defaults.env
    cd ..
    octoblu-stack-generator --output prod --stack octoblu --init --overrides
    octoblu-stack-generator --output prod --stack octoblu --overrides
    cd dev
    docker stack deploy --compose-file ./docker-compose.yml octoblu

    Stacks

    Stacks are mostly Docker Stacks with a hack using volume labels to compose multiple stacks together. A stack represents a group of services to be run in the cluster. Each service has an environment file that controls its settings.

    In order to change variables in each service file, simply edit the defaults.env file in your ouput dir and run octoblu-stack-generator again with the appropriate options.

    To run a subset of Octoblu, run octoblu-stack-generator --stack {stackname} and deploy the stack.

    An example output dir:

    .
    ├── defaults.env
    ├── docker-compose.yml
    └── env.d
        ├── meshblu-core-dispatcher.env
        └── meshblu-core-worker-webhook.env
     
    1 directory, 4 files

    Available Stacks

    • octoblu-development

    • bootstrap-development

    • bootstrap

    • octoblu

    • flows

    • meshblu-core

    • meshblu-firehose-socket.io

    • meshblu-http

    • traefik

    Overrides

    You can override the default structure of the stack, or include additional environment variables. This allows you to keep your own custom modifications yet stay in sync with the master of this project.

    Create an overrides directory in your outputDirectory. You can create overrides/stacks or overrides/templates/serviceName.

    This is especially useful for adding HTTP and Let's Encrypt support to traefik using your own domain.

    Example Traefik Override

    overrides/stacks/traefik.yml

    services:
      traefik:
        command: >
          traefik
            --docker
            --docker.swarmmode
            --docker.watch
            --web
            --entryPoints='Name:http Address::80 Redirect.EntryPoint:https'
            --entryPoints='Name:https Address::443 TLS'
            --defaultEntryPoints=http,https
            --acme
            --acme.onhostrule=true
            --acme.ondemand=true
            --acme.dnsprovider=digitalocean --acme.domains='your-domain.io'
            --acme.entrypoint=https
            --acme.acmelogging
            --acme.storage=/acme/acme.json --acme.email="acme@your-domain.io"
     
    # Add this if you want to test lets encrypt without violating rate limits 
    # remove it to go back to production 
    #--acme.caServer="https://acme-staging.api.letsencrypt.org/directory" 

    overrides/templates/traefik/environment.json

    {
      "DO_ACCESS_TOKEN" : "my-digital-ocean-access-token"
    }

    Keywords

    Install

    npm i octoblu

    DownloadsWeekly Downloads

    4

    Version

    1.0.4

    License

    MIT

    Last publish

    Collaborators

    • iamruinous
    • octoblu-user