The Steerfile

The Steerfile is a file that you add to your docker-based application. The most basic form a Steerfile can take has already been shown in the Getting Started page:

dockerfile 'Dockerfile'

expose 8080

But what does this all mean?

Steerfile Statements

A Steerfile is made up of statements, which are different commands followed by some parameters. Each command is just a ruby method so you can call it that way. Only the dockerfile command is required. All the other commands are either not required or have defaults.

• plugin - Takes 1 parameter: the name of the plugin you wish to use in this Steerfile.

# Example
plugin :git_submodule

See plugins to find available plugins and their usage

• dockerfile - This command is always required. Takes 1 parameter: the name of the Dockerfile you want to use with this Steerfile. You only need to use this command once. Using it multiple times will simply cause the last command to be used. It takes relative paths and the paths are relative to where you run Heighliner.

# Example
dockerfile 'Dockerfile'

• service - This command is optional. Use it to define additional containers that should be set up along with your environment. You can use it multiple times to define multiple services. It takes a name parameter (required) and optional parameters: image, command, binds, env.

# example that sets up a redis server for your app
service 'redis'

Parameters:

• image — Docker image to use (defaults to the name)

# example that tells it to use the redis server with the alpine tag from 'myrepo'
service 'redis', image: 'myrepo/redis:alpine'

• command — Command to run inside the container

service 'redis', command: 'redis-server --appendonly yes'

• binds — Volume binds (hash of hostpath: containerpath)

service 'redis', binds: { '/data/redis' => '/data' }

• env — Environment variables (hash of key: value)

service 'redis', env: { 'REDIS_PASSWORD' => 'secret' }

• attach_mount - Takes 2 parameters: The first parameter is the relative path of a folder or a file outside the container and the second parameter is its absolute path inside the container. This is only used when heighliner attach or heighliner up -a is used. This will mount the file or folder inside the container and sync their contents. If the file you specified does not exist, Heighliner will create a folder where you specify it and then mount that folder inside the container. You can specify as many of these as you want.

# Example to mount the `app` directory into the container's `/srv/files/app`
attach_mount 'app', '/srv/files/app'

• expose - Takes 1 parameter: The port of the server running inside the container. This port is not exposed on the host, so it will not occupy a port on the computer you run heighliner on. Instead, Heighliner will select a random port on the host computer to forward traffic to and from. You can only use this statement once. If you have multiple of these statements the last one will be used.

# Example to expose the port 3636
expose 3636

• app_params - Takes 1 parameter: A string of parameters to the docker run command to add custom environment variables with. Please refer to the docker documentation to see what kinds of parameters you can pass to the docker run command. By default this is just an empty string. You can only pass one of these. Any newline characters in the string will be converted into spaces.

# Example
app_params '-e INTERACTIVE=no'

• type - Takes 1 parameter: Right now the only parameter it can take is :http. If this parameter is specified, heighliner will poll the application until it receives a 200 status code before it closes when you use heighliner up If it doesn't it will close with a status code of 1.

# Example
type :http

• db_reset_command - Takes 1 parameter: A command to reset the database. This command is optional. By default this parameter is echo "no db to reset". You can only specify one of these. If you have multiple of these commands only the last one will be used.

# Example if running this command drops the db and recreates it.
db_reset_command 'rake db:reset'

• force_platform - Forces the Docker platform for all containers (e.g., linux/amd64 on Apple Silicon).

force_platform 'linux/amd64'

• db - Takes 1 parameter in the form of a hash

# Default settings
{
  image: 'none',
  platform: '',
  port: 1234,
  data_dir: '/tmp/data',
  params: '',
  commands: 'echo "no db"',
  waitscript: 'echo "no dbwait"',
  waitscript_params: ''
}

You can use this to customize the database that you wish to use with your server.

Alternative Steerfile

If you want change your dev environment for a project, but don't want to overwrite the project's Steerfile/Dockerfile, you can use an alternative Steerfile.

An alternative Steerfile is located at ~/heighlinerfiles/Steerfile.<app name>, where <app name> is replaced with the name you provided when calling heighliner init.

If Heighliner detects an alternative Steerfile, it will use it instead of the Project root one. Some things to watch out for:

• Of course, your app may behave differently if you change your environment from the project's default.
• The dockerfile declaration is still relative to the project root. If you want to use a custom Dockerfile as well, you need to specify its full path in the Steerfile.
• If the project's Steerfile or Dockerfile changes, you'll have to update your custom ones manually.