kschu91/gogs

Table of Contents

1. Description
2. Setup - The basics of getting started with gogs
   • What gogs affects
   • Setup requirements
   • Beginning with gogs
3. Usage - Configuration options and additional functionality
4. Reference - An under-the-hood peek at what the module is doing and how
5. Limitations - OS compatibility, etc.
6. Development - Guide for contributing to the module

Description

This module install and configure Gogs (A painless self-hosted Git service.) by installing Gogs from binary instead of using any thirdparty PPA´s. You are completely free to configure Gogs for your needs since this module allows dynamic configuration for the custom/conf/app.in file.

Setup

What gogs affects

• Gogs will be installed in /opt/gogs (can be changed).
• A service will be installed with an init script.
• By default a user and the correspendig group will be created (can be turned off).
• By default curl, wget, tar, git will be installed if not already installed on your system (can be turned off).
• On RedHat, CentOS and OracleLinux the initscripts package will be installed by default if not already done (can be turned off).

Setup Requirements

MySQL or PostgreSQL are not being installed by this module. Make sure those services are installed before using Gogs. Have a look at the prerequisites documentation of Gogs for a quick step into it.

Note: Currently puppet 3 and 4 is supported. But the support of puppet 3.x will be dropped in future versions of this module.

Beginning with gogs

You can simply include the gogs module to get started with the defaults. Check out the reference to see what the defaults are. After that you can visit Gogs via http://youhost.tld:3000 and you can follow the installation instructions from the gogs install tool.

include ::gogs

But be aware, if you change anything within gogs installation tool puppet will overwrite the app.ini on its next run. You rather should define all your configurations within puppet. A minimal setup with a mysql database should look like this:

class { '::gogs':
    app_ini_sections => {
        'database' => {
            'DB_TYPE' => 'mysql',
            'HOST'    => 'localhost:3306',
            'NAME'    => 'gogs',
            'USER'    => 'gogs',
            'PASSWD'  => 'mysecretpasswd',
        },
        'security' => {
            'SECRET_KEY' => 'mysecretkey',
            'INSTALL_LOCK' => true,
        },
    },
}

Note: You should always set INSTALL_LOCK configuration to true. Otherwise the installer is open for everyone.

Usage

The most common way of using the gogs module with a minimal set of custom configuration is the following.

Note: You are able to provide any available Gogs configuration in app_ini and app_ini_sections. For a complete list of available configuration have a look at the Gogs configuration cheat sheet.

class { '::gogs':
    app_ini => {
        'APP_NAME' => 'My Fancy GIT Service'
    },
    app_ini_sections => {
        'server'   => {
            'DOMAIN'    => 'git.example.com',
            'HTTP_PORT' => 8080,
        },
        'database' => {
            'DB_TYPE' => 'mysql',
            'HOST'    => 'localhost:3306',
            'NAME'    => 'gogs',
            'USER'    => 'gogs',
            'PASSWD'  => 'mysecretpasswd',
        },
        'security' => {
            'SECRET_KEY' => 'mysecretkey',
            'INSTALL_LOCK' => true,
        },
    },
}

Note: Currently the module will not create an admin user for you. You can do this by using the gogs cli: gogs admin create-user --name="john.doe" --password="supersecret" --email="john@doe.com" --admin

Reference

Parameters

version

You can specify a specific version. Just tell the module which version you want to install. For example 0.9.113. The default version is latest and the module will then fetch the latest version from Github automatically.

class { '::gogs':
    version => '0.9.113'
}

installation_directory

If you need to change the installation directory you can do this by specifieng this parameter. By default gogs will be installed in /opt/gogs

class { '::gogs':
    installation_directory => '/home/git/gogs'
}

repository_root

By default git repositories are stored in /var/git. Use this parameter to change the default path.

class { '::gogs':
    repository_root => '/home/git/gogs-repositories'
}

app_ini

A hash of available Gogs configuration. For a full list please have a look at the configuration cheat sheet.

class { '::gogs':
    app_ini => {
        'APP_NAME' => 'My Fancy GIT Service'
    },
}

app_ini_sections

Hash of available Gogs configurations that belong to a specific section. For a full list please have a look at the configuration cheat sheet.

class { '::gogs':
    app_ini_sections => {
        'server'   => {
            'DOMAIN'    => 'git.example.com',
            'HTTP_PORT' => 3000,
        },
        'database' => {
            'DB_TYPE' => 'mysql',
            'HOST'    => 'localhost:3306',
            'NAME'    => 'gogs',
            'USER'    => 'gogs',
            'PASSWD'  => 'mysecretpasswd',
        },
        'security' => {
            'SECRET_KEY' => 'mysecretkey',
        },
        'service'  => {
            'REQUIRE_SIGNIN_VIEW'  => true,
            'DISABLE_REGISTRATION' => true,
        },
    },
}

manage_user

Set this to false if you want to manage the user under which Gogs is running to handle by yourself. By default this is set to true and the module will create the user and the corresponding group.

class { '::gogs':
    manage_user => false
}

manage_packages

Set this to false if you want to manage the dependent packages by yourself. By default this is set to true and the module will install all the dependent packages by itself. The packages being installed are curl, wget, tar, git and on RedHat, CentOS and OracleLinux the initscripts package. If you set this to false make sure the packages are installed before using this module.

class { '::gogs':
    manage_packages => false
}

manage_home

Set this to false if you want to manage/create the users home directory by yourself. By default this is set to true and the module will create the users home directory for you. This parameter have no effect if manage_user is set to false. No home directory will then be created/managed by this module.

class { '::gogs':
    manage_home => false
}

owner

Use this parameter to change the user under which Gogs is running. By default the users name is git.

class { '::gogs':
    owner => 'johndoe'
}

group

Use this parameter to change the group under which Gogs is running. By default the group name is git.

class { '::gogs':
    group => 'company'
}

service_ensure

By default this parameter is set to running. Set it to stopped if you don´t want to start gogs by puppet.

class { '::gogs':
    service_ensure => 'stopped'
}

service_name

By default the service is named gogs. If you ever need to change that you can do this by setting this parameter. You should NOT change the service name after your first puppet run. Otherwise you may run into issues with two services and already blocked ports.

class { '::gogs':
    service_name => 'gogitsgogs'
}

log_path

By default the log_path points to the folder log relative to the installation_directory, which is /opt/gogs/log per default.

class { '::gogs':
    log_path => '/var/log/gogs'
}

Changing it to /var/log/gogs for example, will force gogs to write a gogs.log file in /var/log/gogs.

sysconfig

Normally there is no need to change this. But if you need to change variables for the daemon script anyways use this parameter. The provided variables are stored in a sysconfig file depending on your distribution and service name (e.g /etc/default/gogs) and are then automatically interpreted by the daemon scripts.

The configuration key to pass depends on your OS. For example on Debian the user variable is named USER and on CentOS it´s named GOGS_USER. Take a look into the provided init scripts of Gogs to make sure you pass the correct variables. Otherwise your service may fail silently.

class { '::gogs':
    sysconfig => {
        'NAME' => 'gogitsgogs',
        'USER' => 'johndoe',
    }
}

puppetstats_enabled

The gogs module is using puppetstats.com to ensure that the module is developed and maintained against it´s real usage, since I do not want to support old puppet versions when almost nobody is using them anymore. puppetstats.com tracks anonymous usage statistics of the puppet environment where gogs is running. By default puppetstats_enabled is set to true, but of course you can opt-out from that. Simply set puppetstats_enabled to false.

class { '::gogs':
    puppetstats_enabled => false
}

Limitations

This module is developed and tested on Ubuntu, Debian, CentOS and OracleLinux (RedHat should also work). But other distributions are currently not supported. Do not hesitate to create an issue on Github if you are facing any trouble.

Development

You are very welcome to contribute on this module. The source code is available on GitHub. Please follow the contributing instructions from puppet.

2018-04-01 Release 1.4.0

• Added parameter log_path, which allows setting the root path where gogs will store logs.
• Unsupported operating systems are now getting useful warning, but do not fail anymore.
• Refactored internal class dependencies to make the code more maintainable.
• Refactored scripts, there are now stored in installation_directory rather than storing them in tmp.

2018-03-31 Release 1.3.0

• Added puppetstats.com
• Fixed: gogs service restart is triggered on each puppet run. Which has caused gogs to restart on each puppet run. Now it get´s only restarted if the version needs to be changed or the configuration has changed.

2017-08-06 Release 1.2.0

• Added new parameter manage_packages to optionally disable installing of dependent system packages automatically. Check the README for more details.
• Drop support for Ruby version 1.9
• Drop support for puppet version 3.5 - 3.7 (3.8 is the minimum now)

2017-03-07 Release 1.1.0

• Added support for OracleLinux (thanks to wfsaxton for requesting the pull request).

2017-03-04 Release 1.0.1

• Bugfix for older Ubuntu versions which does not start/stop the daemon correctly because of wrong init scripts error codes

2017-02-28 Release 1.0.0

• Fixed issue #4 that does not allow overwriting of default values which have an impact either on sysconfig or app.ini values.
• Dependent system packages (eg. git, curl, etc.) are now getting installed automatically if not already there.
• The parameter sysconfig has changed! Check the README for further details.
• Changing ownership after the first run is now possible.

2017-02-22 Release 0.2.0

• Added support for CentOS and Debian.
• Added acceptance tests for CentOS, Debian and Ubuntu.
• Clarify requirements in README.md

2017-02-19 Release 0.1.0

First version of gogs puppet module.