From 22c99ca22caf0b112b9deebe368720eaa23fa00b Mon Sep 17 00:00:00 2001 From: ByteOtter Date: Fri, 16 Jun 2023 11:40:06 +0200 Subject: [PATCH] Expand Readme and create contributing guide --- CONTRIBUTING.md | 42 +++++++++++++ README.md | 159 +++++++++++++++++++++++++++++++++++++++++++++++- 2 files changed, 199 insertions(+), 2 deletions(-) create mode 100644 CONTRIBUTING.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..773fea6 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,42 @@ +# Contributing + +Thank you for your interest in contributing to Cobbler-TFTP.
+This guide will show you how to set up your development environment. + + +## Getting started + +To get started first you need to +[fork this repository](https://docs.github.com/en/get-started/quickstart/fork-a-repo), +so you have your very own copy of the Cobbler-TFTP source code in you own GitHub profile. + +After this is done, +[clone your fork](https://docs.github.com/en/repositories/creating-and-managing-repositories/cloning-a-repository) +clone your fork to a directory of your choosing and change to that directory. + +Once in there you can add the original repository as a git remote so you can pull the latest changes without extra +steps. + +You can do so like this: + +```bash +git remote add upstream git@github.com:cobbler/cobbler-tftp.git +``` + +After this step, you can simply pull the latest changes of Cobbler-TFTP with `git pull upstream main`. + +## Setting up the environment + +After you have cloned the source code you need to set up a virtual environment using either +[virtualenv](https://virtualenv.pypa.io/en/latest/) or [pyenv](https://github.com/pyenv/pyenv) to make sure your +system does not affect the integrity of your changes. + +When this is completed, you then need to install all requirements.
+You can do so by running this command: + +```bash +pip install -e .[tests_require,lint_requires,doc] +``` +Pip will then install Cobbler-TFTP alongside all of the additional dependencies required for contributing. + +Now you can start making changes to Cobbler-TFTP! \ No newline at end of file diff --git a/README.md b/README.md index 86affc1..c98919e 100644 --- a/README.md +++ b/README.md @@ -1,3 +1,158 @@ -# cobbler-tftp +# Cobbler-TFTP -Experimental - Cobbler stateless TFTP server \ No newline at end of file +[![Codacy Badge](https://app.codacy.com/project/badge/Grade/97c9e642afd646e98b9250e2959aae12)](https://app.codacy.com/gh/cobbler/cobbler-tftp/dashboard?utm_source=gh&utm_medium=referral&utm_content=&utm_campaign=Badge_grade) +[![Codacy Badge](https://app.codacy.com/project/badge/Coverage/97c9e642afd646e98b9250e2959aae12)](https://app.codacy.com/gh/cobbler/cobbler-tftp/dashboard?utm_source=gh&utm_medium=referral&utm_content=&utm_campaign=Badge_coverage) +[![Tests](https://github.com/cobbler/cobbler-tftp/actions/workflows/testing.yml/badge.svg)](https://github.com/cobbler/cobbler-tftp/actions/workflows/testing.yml) +[![Documentation Status](https://readthedocs.org/projects/cobbler-tftp/badge/?version=latest)](https://cobbler-tftp.readthedocs.io/en/latest/?badge=latest) + +[![Matrix](https://img.shields.io/matrix/cobbler-community:matrix.org?label=Chat%20on%20Matrix&logo=matrix)](https://app.element.io/#/room/#cobbler_community:gitter.im) + +--- + +Cobbler-TFTP is a lightweight CLI application written in Python that serves as a stateless TFTP server. +It seamlessly integrates with Cobbler to generate and serve boot configuration files dynamically to managed machines. + + +## Features + +- Stateless TFTP server for network booting and provisioning +- Interoperates with Cobbler for centralized management and configuration deployment +- Dynamic on-demand generation of boot configuration files for efficient resource use +- Configurable daemon process + +## Installation (WIP) + +Please note that Cobbler-TFTP is currently still in an early development stage and is not yet ready to be released. +However, these methods of Installation will be available: + +### Installation Requirements + +To install and use Cobbler-TFTP, please make sure you have *at least Python 3.6* installed. + +### Install via `pip` + +Cobbler-TFTP is published to PyPi. +To install it, please make sure that your system fulfills the installation requirements listed above and has `pip`, +the Python package manager, installed. + +To install Cobbler-TFTP you can then simply run: +```bash +pip install cobbler-tftp +``` + +### Install on Linux via Package manager + +Cobbler-TFTP is packaged for a number of Linux distributions. + +Note: The native linux packages do not yet exist. +These instructions are just representing what we have planned for the near future. + +#### Install on openSUSE + +```bash +sudo zypper install cobbler-tftp +``` + +#### Install on Fedora + +```bash +sudo dnf install cobbler-tftp +``` + +#### Install on Debian, Ubuntu and Linux Mint + +```bash +sudo apt install cobbler-tftp +``` + + + +## Usage + +You can use Cobbler-TFTP out of the box when providing it your Cobbler API credentials. + +You can do so with a `settings.yml`configuration file, environment variables and/or command line flags. + +To run Cobbler-TFTP simply run: + +```bash +cobbler-tftp +``` + +### Configuring Cobbler-TFTP + +The default parameters for Cobbler-TFTP's application settings will be taken, if no configuration file, +command line argument or environment variable can be found, will be as follows: + +```yaml +schema: 1.0 # The version of the configuration schema to use +auto_migrate_settings: false # Automatically migrate to the newest configuration schema +is_daemon: true # Run Cobbler-TFTP as a daemon +cobbler: + uri: "http://localhost/cobbler_api" # uri of your Cobbler API + username: "cobbler" # Username for Cobbler + password: "cobbler" + password_file: "/etc/cobbler-tftp/cobbler_password" # File containing your Cobbler password. +``` + +**Please note** that the `password` and `password_file` settings are mutually exclusive. +Custom configuration files containing both parameters will not be accepted. + +#### Using a configuration yaml file + +Cobbler-TFTP can be configured using a custom `settings.yml` file. +Note, that this file must contain at least all parameters listed above. + +To pass the file on you can pass the file location on as a CLI argument using the `-c` or `--config` flag: + +```bash +cobbler-tftp -c path/to/your/file.yml +``` + +#### Using environment variables + +You can set certain parameters of Cobbler-TFTP's behavior by using environment variables. +These will override the configuration from your configuration file. + +Cobbler-TFTP will automatically search for environment variables in this format: + +``` +COBBLER_TFTP______<...>__= +``` + +For example your variables might look like this: + +``` +COBBLER_TFTP__IS_DAEMON=true +``` + +or, in case of your Cobbler settings: + +``` +COBBLER_TFTP__COBBLER__URI=http://your.domain.com/cobbler_api +``` + +#### Using CLI arguments + +You can also provide Cobbler-TFTP with CLI arguments to override some or all of the above parameters. + +These must be given in the format: + +``` +..<...>.= +``` + +These arguments will override all of the parameters above and will be lost when the service is stopped and restarted. + +We advise you to use this option for testing purposes only. + +## Documentation + +You can find our latest documentation on our [Read the Docs Page](https://cobbler-tftp.readthedocs.io/en/latest/) + +## Contributing + +If you would like to contribute to this project, you can take a look at our [contributing guide](./CONTRIBUTING.md) +for a detailed guide on how you can help to make Cobbler-TFTP the best int can be. + +We greatly appreciate any contribution!