diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/Configuration.md | 38 | ||||
| -rw-r--r-- | docs/Install as a debian package.md | 40 | ||||
| -rw-r--r-- | docs/Install as a python module.md | 43 | ||||
| -rw-r--r-- | docs/README.md | 14 | ||||
| -rw-r--r-- | docs/Start automatically on boot.md | 53 | ||||
| -rw-r--r-- | docs/Useful commands.md | 11 |
6 files changed, 196 insertions, 3 deletions
diff --git a/docs/Configuration.md b/docs/Configuration.md index b911048..953385d 100644 --- a/docs/Configuration.md +++ b/docs/Configuration.md @@ -1,5 +1,25 @@ -# Configuration -The configuration file is formatted in `JSON`. The possible root elements are +# Command line options and environment variables + +```Git-Auto-Deploy``` supports a number of configurable options. Some of them are available using command line options, where others are only configurable from the config file. Below is a list of the options made available from the command line. Every command line option has also a corresponding environemnt variable. In the cases where a corresponding config file attribute is available, that attribute name is listed. + +There is also support for supplying configuration options for up to one repository using environmetn variables. Variable names and descriptios are available in the section (Repository configuration using environment variables)[#eepository-configuration-using-environment-variables]. + +The list of available command line options can also be seen by invoke the application with the argument ```--help```. + +Command line option | Environment variable | Config attribute | Description +---------------------- | -------------------- | ---------------- | -------------------------- +--daemon-mode (-d) | GAD_DAEMON_MODE | | Run in background (daemon mode) +--quiet (-q) | GAD_QUIET | | Supress console output +--config (-c) <path> | GAD_CONFIG | | Custom configuration file +--pid-file <path> | GAD_PID_FILE | pidfilepath | Specify a custom pid file +--log-file <path> | GAD_LOG_FILE | logfilepath | Specify a log file +--host <host> | GAD_HOST | host | Address to bind to +--port <port> | GAD_PORT | port | Port to bind to +--force | GAD_FORCE | | Kill any process using the configured port +--ssh-keygen | GAD_SSH_KEYGEN | | Scan repository hosts for ssh keys + +# Configuration file options +The configuration file is formatted according to a `JSON` inspired format, with the additional feature of supporting inline comments. The possible root elements are as follow: - **pidfilepath**: The path where `pid` files are kept. @@ -129,4 +149,16 @@ Execute script upon GitLab CI successful build of `master` branch. } ] } -```
\ No newline at end of file +``` + +# Repository configuration using environment variables + +It's possible to configure up to one repository using environment variables. This can be useful in some specific use cases where a full config file is undesired. + +Environment variable | Description +-------------------- | -------------------------- +GAD_REPO_URL | Repository URL +GAD_REPO_BRANCH | +GAD_REPO_REMOTE | +GAD_REPO_PATH | Path to where ```Git-Auto-Deploy``` should clone and pull repository +GAD_REPO_DEPLOY | Deploy command diff --git a/docs/Install as a debian package.md b/docs/Install as a debian package.md new file mode 100644 index 0000000..7cce207 --- /dev/null +++ b/docs/Install as a debian package.md @@ -0,0 +1,40 @@ +# Install as a debian package (experimental) + +Below is instructions on how to create a debian (.deb) package using stdeb. You can follow the instructions below to build the .deb package, or use the prepared script (platforms/debian/scripts/create-debian-package.sh) that will do the same. Once the package is created, you can install it using ```dpkg -i```. A sample configuration file as well as a init.d start up script will be installed as part of the package. + +### Install dependencies + +Install stdeb and other dependencies + + apt-get install python-stdeb fakeroot python-all + +### Download and build + + git clone https://github.com/olipo186/Git-Auto-Deploy.git + cd Git-Auto-Deploy + + # Generate a Debian source package + python setup.py --command-packages=stdeb.command sdist_dsc -x platforms/debian/stdeb.cfg + + # Copy configuration files + cp -vr ./platforms/debian/stdeb/* ./deb_dist/git-auto-deploy-<version>/debian/ + + # Copile a Debian binary package + cd ./deb_dist/git-auto-deploy-<version> + dpkg-buildpackage -rfakeroot -uc -us + +### Install + +When installing the package, a sample configuration file and a init.d start up script will be created. + + dpkg -i git-auto-deploy-<version>.deb + +### Configuration + + nano /etc/git-auto-deploy.conf.json + +### Running the application + + service git-auto-deploy start + service git-auto-deploy status + diff --git a/docs/Install as a python module.md b/docs/Install as a python module.md new file mode 100644 index 0000000..245091d --- /dev/null +++ b/docs/Install as a python module.md @@ -0,0 +1,43 @@ +# Install as a python module (experimental) + +## Download and install + +Install using [pip](http://www.pip-installer.org/en/latest/), a package manager for Python, by running the following command. + + pip install git-auto-deploy + +If you don't have pip installed, try installing it by running this from the command +line: + + curl https://raw.github.com/pypa/pip/master/contrib/get-pip.py | python + +Or, you can [download the source code +(ZIP)](https://github.com/olipo186/Git-Auto-Deploy/zipball/master "Git-Auto-Deploy +source code") for `Git-Auto-Deploy` and then run: + + python setup.py install + +You may need to run the above commands with `sudo`. + +Once ```Git-Auto-Deploy``` has been installed as a python module, it can be started using the executable ```git-auto-deploy```. During installation with pip, the executable is usually installed in ```/usr/local/bin/git-auto-deploy```. This can vary depending on platform. + +## Configuration + +Copy the content of [config.json.sample](./config.json.sample) and save it anywhere you like, for example ```~/git-auto-deploy.conf.json```. Modify it to match your project setup. [Read more about the configuration options](./docs/Configuration.md). + [](./docs/Configuration.md) + +## Running the application + +Run the application using the executable ```git-auto-deploy``` which has been provided by pip. Provide the path to your configuration file as a command line argument. + referencing the ```gitautodeploy``` module (the directory ```Git-Auto-Deploy/gitautodeploy```). + + git-auto-deploy --config ~/git-auto-deploy.conf.json + +## Start automatically on boot using crontab + +The easiest way to configure your system to automatically start ```Git-Auto-Deploy``` after a reboot is using crontab. Open crontab in edit mode using ```crontab -e``` and add the entry below. + +When installing with pip, the executable ```git-auto-deploy``` is usually installed in ```/usr/local/bin/git-auto-deploy```. It is a good idea to verify the path to ```git-auto-deploy``` before adding the entry below. + + @reboot /usr/local/bin/git-auto-deploy --daemon-mode --quiet --config /path/to/git-auto-deploy.conf.json + diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 0000000..51d629d --- /dev/null +++ b/docs/README.md @@ -0,0 +1,14 @@ +# Git-Auto-Deploy documentation + +# Documents + +* [Configuration options](./Configuration.md) +* [Install as a python module (experimental)](./Install as a python module.md) +* [Install as a debian package (experimental)](./Install as a debian package.md) +* [Start automatically on boot (init.d and systemd)](./Start automatically on boot.md) + +# Example workflows + +## Continuous Delivery via Pull requests (GitHub only) + +It's possible to configure Git-Auto-Deploy to trigger when pull requests are opened or closed on GitHub. To read more about this workflow and how to configure Git-Aut-Deploy here: [Continuous Delivery via Pull requests](./Continuous Delivery via Pull requests.md) diff --git a/docs/Start automatically on boot.md b/docs/Start automatically on boot.md new file mode 100644 index 0000000..48977a3 --- /dev/null +++ b/docs/Start automatically on boot.md @@ -0,0 +1,53 @@ +# Start automatically on boot + +```Git-Auto-Deploy``` can be automatically started at boot time using various techniques. Below you'll find a couple of suggested approaches with instructions. + +The following instructions assumes that you are running ```Git-Auto-Deploy``` from a clone of this repository. In such a case, ```Git-Auto-Deploy``` is started by invoking ```python``` and referencing the ```gitautodeploy``` python module which is found in the cloned repository. Such a command can look like ```python /path/to/Git-Auto-Deploy/gitautodeploy --daemon-mode```. + +If you have used any of the alternative installation methods (install with pip or as a debian package), you will instead start ```Git-Auto-Deploy``` using a installed executable. ```Git-Auto-Deploy``` would then be started using a command like ```git-auto-deploy --daemon-mode``` instead. If you have installed ```Git-Auto-Deploy``` in this way, you will need to modify the paths and commands used in the instructions below. + +## Crontab +The easiest way to configure your system to automatically start ```Git-Auto-Deploy``` after a reboot is using crontab. Open crontab in edit mode using ```crontab -e``` and add the following: + + @reboot /usr/bin/python /path/to/Git-Auto-Deploy/gitautodeploy --daemon-mode --quiet + +## Debian and Sys-V like init system. + +Copy the sample init script into ```/etc/init.d/``` and make it executable. + + cp platforms/linux/initfiles/debianLSBInitScripts/git-auto-deploy /etc/init.d/ + chmod 755 /etc/init.d/git-auto-deploy + +**Important:** The init script assumes that you have ```Git-Auto-Deploy``` installed in ```/opt/Git-Auto-Deploy/``` and that the ```pidfilepath``` config option is set to ```/var/run/git-auto-deploy.pid```. If this is not the case, edit the ```git-auto-deploy``` init script and modify ```DAEMON```, ```PWD``` and ```PIDFILE```. + +Now you need to add the correct symbolic link to your specific runlevel dir to get the script executed on each start up. On Debian_Sys-V just do; + + update-rc.d git-auto-deploy defaults + +Fire it up and verify; + + service git-auto-deploy start + service git-auto-deploy status + +## Systemd + +Copy the sample systemd service file ```git-auto-deploy.service``` into ```/etc/systemd/system```; + + cp platforms/linux/initfiles/systemd/git-auto-deploy.service /etc/systemd/system + +Create the user and group specified in git-auto-deploy.service (```www-data```) if those do not exist already. + + useradd -U www-data + +This init script assumes that you have ```Git-Auto-Deploy``` installed in ```/opt/Git-Auto-Deploy/```. If this is not the case, edit the ```git-auto-deploy.service``` service file and modify ```ExecStart``` and ```WorkingDirectory```. + +Now, reload daemons and fire ut up; + + systemctl daemon-reload + systemctl start git-auto-deploy + +Make is start automatically on system boot; + + systemctl enable gitautodeploy + + diff --git a/docs/Useful commands.md b/docs/Useful commands.md new file mode 100644 index 0000000..fb25613 --- /dev/null +++ b/docs/Useful commands.md @@ -0,0 +1,11 @@ + +# Create debian package +apt-get install python-stdeb fakeroot python-all + +https://pypi.python.org/pypi/stdeb/0.8.5 +python setup.py --command-packages=stdeb.command –package=git-auto-deploy bdist_deb +python setup.py --command-packages=stdeb.command sdist_dsc bdist_deb + + +# Debianize +python setup.py --command-packages=stdeb.command debianize |