Table of Contents

1. Table of Contents
2. Installation
3. Usage
4. Proxy
   1. Getting Started with the Proxy
   2. Proxy Configuration
   3. Stopping the Proxy
   4. Troubleshooting
5. Development
   1. Workflow
   2. Releasing a new version
6. Dockerizing an application
   1. Generate templates (sc dockerize)
   2. Customize templates
7. Generating a Helm Chart
8. Contributing
9. TODO

StackCar

Stack Car is an opinionated set of tools around Docker and Rails. It provides convenent methods to start and stop docker-compose, to deploy with rancher and a set of templates to get a new Rails app in to docker as quickly as possible.

Table of Contents

• Installation
• Usage
• Development
• Dockerizing an Application
• Generating a Helm Chart

Installation

Because stack_car will be used to run your application in side of Docker, you want to install stack car in to your system Ruby instead of putting in your applications Gemfile

gem install stack_car

Usage

Commands are accessible via the "sc" short cut. Note: this will need to be in your command path in front of the spreadsheet command (sc), which is a fairly archaiac unix spreadsheet tool. We're guessing you don't edit a lot of spreadsheets in your terminal, but if you do, we also figure you can override your path order pretty easily. Many of these commands have short versions or alias to make remembering them easier. If there are obvious aliases missing, PRs are welcome.

Commands:
  stack_car bundle_exec ARGS  # wraps docker compose exec web bundle exec unless --service is used to specify (sc be ARGS)
  stack_car console ARGS      # shortcut to start rails console
  stack_car dockerize DIR     # Will copy the docker templates in to your project, see options for supported dependencies
  stack_car exec ARGS         # wraps docker compose exec web unless --service is used to specify
  stack_car help [COMMAND]    # Describe available commands or one specific command
  stack_car stop              # starts docker compose with rebuild and orphan removal, defaults to all
  stack_car up                # starts docker compose with rebuild and orphan removal, defaults to web
  stack_car walk ARGS         # wraps docker compose run web unless --service is used to specify
  stack_car proxy up          # starts proxy container for SSL termination
  stack_car proxy down        # stops running proxy container
  stack_car proxy cert        # generates SSL certificates for local development, uses *.localhost.direct

Proxy

StackCar has a built-in proxy designed to simplify local SSL development. The proxy provides SSL termination for your web services, allowing you to run your applications with HTTPS locally.

Getting Started with the Proxy

To use the StackCar proxy:

1. Download and Install the SSL certificates for local development:

   sc proxy cert
   

   This will download the SSL certificates for *.localhost.direct. This only needs to be done once per version of stack_car.

2. Start the proxy:

   sc proxy up
   

3. If you application is running in Docker, make sure you application has labels:

   labels:
    - "traefik.enable=true"
    - "traefik.http.routers.my-app.tls=true"
    - "traefik.http.routers.my-app.entrypoints=websecure"
    - "traefik.http.routers.my-app.rule=HostRegexp(`my-app.localhost.direct`)"
    - "traefik.http.services.my-app.loadbalancer.server.port=3000"
   

4. Access your application using https://my-app.localhost.direct

Proxy Configuration

The proxy configuration can be customized in your docker-compose.yml file. By default, it's configured to handle SSL termination on port 443 and forward traffic to your application services.

Stopping the Proxy

When you're done working with SSL, you can stop the proxy:

sc proxy down

Troubleshooting

• Certificate issues: If your browser doesn't trust the certificate, you may need to add the generated certificate to your system's trust store.
• Port conflicts: Ensure port 443 is available on your local machine.

Development

After checking out the repo, run bin/setup to install dependencies. Then, run rake spec to run the tests. You can run bin/test_sc to run the command but from your local check out. You can also run bin/console for an interactive prompt that will allow you to experiment.

To install this gem onto your local machine

• Run bundle exec rake install

Workflow

Create a dummy rails app

Developing stack_car often requires a rails application for you to run updated commands and templates against. Generate one for this purpose:

• rails new <dummy-app-name>

Make and test your changes

• In stack_car, make your command / template changes
• Run rake install to update your local gem
• In your dummy application, test the updated command
• Commit your changes

Releasing a new version

NOTE: You will need an account for rubygems.org and be made an owner of the stack_car gem in order to release a new version.

• Update the version number in version.rb. Please follow Semantic Versioning guidelines.
• Commit version.rb and create an MR. Once the MR is approved and merged, checkout the main branch and do a git pull.
• Run bundle exec rake release
  • This will create a git tag for the version, push git commits and tags, and push the .gem file to rubygems.org.

Dockerizing an application

Dockerizing your application with stack_car can be thought of in 2 steps:

• Generate the file templates
• Customize provided templates to the requirements of the application

Set MERGE tool When using stack_car to dockerize an app, it might be necessary to merge templates as opposed to completely overwriting them. To set a tool run:

export THOR_MERGE=<editor>

Alternatively, set it in your shell's rc file (~/.bashrc, ~/.zshrc, etc.)

With THOR_MERGE set, you can enter m at the command prompt when there is a conflict between app and sc template files.

Note: For best experience, set THOR_MERGE to GUI text editor (ie. code or atom).

Initiating a merge pulls 2 versions of the file to the editor. One is what is proposed by stack_car, the other is the original. Add what you need from the template version to the original file and save the changes.

Generate templates (sc dockerize)

You can generate requisite files for running your application for local development in Docker with the dockerize command.

To dockerize your application:

• cd into your project dir
• Run sc dockerize to generate files, appending service flags to scaffold any other services your application requires
  • For example:
  • For rails/postgres: sc dockerize --postgres
  • For rails/mysql/redis: sc dockerize --mysql --redis

This command will provide:

• Dockerfile
• docker-compose.yml
• .env* files
• ops files to get you set up for running your application with nginx.

Customize templates

stack_car will have provided sensible defaults for your services but customization will be required per needs of each project (ie api tokens and email configuration where applicable).

Customization workflow

• Do a text search to find and replace any instances CHANGEME in the generated files
• Add any general environment variables to .env
  • This sets defaults for all docker compose environments
• Add any development environment variables to .env.development
  • These set up any new values or overrides specific to your development env
• Run sc build to build your image
  • On failed build, browse the terminal output to track down and squash any misconfigurations. Rebuild
• Upon successful build, run sc up to spin up project
  • If you get errors, browse the terminal output to track down and squash any misconfigurations (refer to the Docker dashboard to see separate logs for each service)
• Visit site at localhost:3000
  • Alternatively, visit it at the host you have specified to work with Dory
• Note: Depending on the DB required by your application, you will need to create the DB. You need to do that within from the container:
  • Using the bundle-exec command: sc bundle-exec db:create
  • Shelling in and running in the container shell: bash sc exec bash bundle exec rails db:create

Once all services are running and speaking to each other you are good to go.

Tips:

• Any changes to Dockerfile will require sc build for the changes to manifest
• Changes to docker-compose.yml do not require rebuild unless you have changed the image

Generating a Helm Chart

stack_car's dockerize command can be used in conjunction with available flags to generate a Helm chart template for your application. You will need to create the values files with necessary configuration values from the sample-values provided by stack_car, but the command will effectively give you the baseline Notch8 template (scripts, template files, template helpers, sample values file) for a Helm base Kubernetes deploy

The following examples are to be run in the repo of the application you are creating the chart for.

To generate a Helm chart template

• sc dockerize --helm
  • This command without additional flags will only generate Rails web related template files

In broad strokes adding additional flags signals stack_car to generate template files for other services. Note that any configuration that would normally be applied for these services in a non Helm context (without the --helm flag) still apply.

For example:

• sc dockerize --helm --fcrepo --solr
  • This command will add templates for the fcrepo service and add a solr chart dependency in the Chart.yaml (You can think of Chart.yaml like the Gemfile or package.json of a Helm chart)

Creating values files

Values files allows you to configure your helm deploy from number of web instances to hostname for your ingress to environment variables required by your application.

When starting from a new helm chart, you'll want to copy the sample values file to one named after the environment you're creating a deployment for.

For example: cp sample-values.yaml staging-values.yaml

Note: You will do this once for every environment you'd like to deploy

Handling values files

Since values files are likely to contain sensitive information like API keys, they should never be committed to your repository. The scripts that stack_car includes in your chart simplifies encrypting and decrypting values for version control.

Example workflow (given values file is already created):

• Edit values file
• bin/encrypt-secrets
  • This command will create/update staging-values.yaml.enc
• Commit and push

When pulling down a repo or branch, you will need to start by decrypting.

Example:

• bin/decrypt-secrets

Contributing

Bug reports and pull requests are welcome on Gitlab at https://gitlab.com/notch8/stack_car.

TODO

• move .env files to dot style
• make .env secret by default

• update .gitlab to latest (see learn and ansur)

• Fill out readme

• Implement deploy

• Implement deploy templates

• Implement database dump and restore

• Implement secret sync

• Specs