- Description
- Setup - The basics of getting started with gogs
- Usage - Configuration options and additional functionality
- Reference - An under-the-hood peek at what the module is doing and how
- Limitations - OS compatibility, etc.
- Development - Guide for contributing to the module
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.
- 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,gitwill be installed if not already installed on your system (can be turned off). - On
RedHat,CentOSandOracleLinuxtheinitscriptspackage will be installed by default if not already done (can be turned off).
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.
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_LOCKconfiguration totrue. Otherwise the installer is open for everyone.
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_iniandapp_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="[email protected]" --admin
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'
}
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'
}
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'
}
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'
},
}
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,
},
},
}
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
}
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
}
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
}
Use this parameter to change the user under which Gogs is running. By default the users name is git.
class { '::gogs':
owner => 'johndoe'
}
Use this parameter to change the group under which Gogs is running. By default the group name is git.
class { '::gogs':
group => 'company'
}
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'
}
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'
}
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.
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',
}
}
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
}
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.
You are very welcome to contribute on this module. The source code is available on GitHub. Please follow the contributing instructions from puppet.