docksal

Table of Contents

1. Description
2. Setup - The basics of getting started with docksal
   • What docksal affects
   • Setup requirements
   • Beginning with docksal
3. Usage - Configuration options and additional functionality
4. Limitations - OS compatibility, etc.
5. Development - Guide for contributing to the module

Description

Installs and configures the docksal (github.com/docksal/docksal) program both for use by individual developers and in the 'CI' configuration. Does not manage configurations.

Setup

What docksal affects

Installs the fin cli to /usr/local/fin so that any user can execute it. Also creates user-specific config files in /.docksal/docksal.env and assumes full control over that file.

Setup Requirements

Requires docker installed. For Mac requires docker installed either natively, or virtualbox installed.

Beginning with docksal

Installing docksal globally is as simple as include docksal. Doing this will not affect individual user configuration files.

Usage

Install and configure docksal for the user demo

Install docksal globally and take control over the demo user's configuration file. This will control the file /home/demo/.docksal/docksal.env and install the default configuration options.

include docksal

docksal::config { 'demo': }

Install and configure docksal for a non-default home path

Although we assume that the home path of the user is /home/<username>, this is not applicable to mac nor to all users. If you need to override this value, it is as simple as:

include docksal

docksal::config { 'root':
  home_directory => '/root'
}

Install and configure with the CI variable set

Docksal CI mode is useful when you want to have CI server managed development environments. You can create the config for that by using:

include docksal

docksal::config { 'ci_user':
  home_directory => '/var/ci_runner',
  ci => true
}

Adding custom environment variables

To add custom environment variables to the docksal.env files managed by puppet, you can pass in the env parameter. For example:

include docksal

docksal::config { 'ci_user':
  home_directory => '/var/ci_runner',
  env => {
    HOSTING_ENVIRONMENT => 'qa'
  }
}

Limitations

• User home directory default doesn't ever work for macos

Reference

Table of Contents

Classes

• docksal: Install and update Docksal.

Defined types

• docksal::config: manage the .docksal/docksal.env file for individual users.

Classes

docksal

Install and update Docksal.

Examples

include docksal

Parameters

The following parameters are available in the docksal class.

version

Data type: String

Specify the version of docksal to install. Can be any of a git tag, commit ref, or branch

Defined types

docksal::config

Configure docksal for an individual user.

Examples

docksal::config { 'username': }

Parameters

The following parameters are available in the docksal::config defined type.

home_directory

Data type: String

The directory within which the config files for docksal live. Defaults to /home/$name.

Default value: "/home/${name}"

ci

Data type: Boolean

Whether to add "CI=1" to the docksal env file.

Default value: false

native_docker

Data type: Boolean

Whether to add "NATIVEDOCKER=1" to the docksal env file.

Default value: false

katacoda

Data type: Boolean

Whether to add "KATACODA=1" to the docksal env file.

Default value: false

Changelog

All notable changes to this project will be documented in this file.

Release 1.4.0

Features

Bugfixes

• Add unit tests for config file owner and group bug.
• Update default prefix to be /usr/local/bin not /usr/local

Known Issues

Release 1.3.0

Features

Bugfixes

• Owner and group for per-user config files should be that user.

Known Issues

Release 1.2.0

Features

• Add the ability to specify arbitrary docksal environment variables.

Bugfixes

• Remove un-supported OSes from metadata.json supported list.

Known Issues

Release 1.1.0

Features

• Release under MIT License.

Bugfixes

Known Issues

Release 1.0.0

Features

• Initial Stable release of puppet docksal module.

Bugfixes

Known Issues