aboutsummaryrefslogtreecommitdiff
path: root/README.md
blob: ea1f3f768697dbad189d743bd8f5596649d721be (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
<!--
SPDX-FileCopyrightText: 2022 Patrick Spek <p.spek@tyil.nl>

SPDX-License-Identifier: AGPL-3.0-or-later
-->

# Bashtard

Bashtard is a small configuration management system written in Bash.

## Getting Started

Since Bashtard is written in bash, you will need to have Bash available in your
`$PATH`. You will also need to have a POSIX compatible system, and the
associated utilities installed and available in your `$PATH`. Lastly, to keep
your setup synchronized, `git` is used.

Once you have everything installed, Bashtard itself can be installed using the
provided `Makefile`.

    make install

### Initialization

When Bashtard is installed, the next step is initializing the system. The `init`
subcommand will perform all necesary steps to create the desired structure in
`/etc/bashtard`.

    bashtard init

It is recommended you create a `git` directory out of `/etc/bashtard` for
synchronization purposes. This will allow you to initialize Bashtard on other
systems by giving it the URL of the git repository as additional argument.

    bashtard init https://git.tyil.nl/tyilnet.git

With the additional argument, it will clone the repository to `/etc/bashtard`,
and then apply any additional steps for the machine you're initializing.

## General Usage

After initializing, you can start using Bashtard. It has the concept of
playbooks, which can either be local or cloned from a remote git repository.

### One-off updates

To perform updates once by hand, use the `sync` subcommand.

    bashtard sync

This will pull the latest changes of remote playbooks, and then run a `sync`
command for each playbook that is used on the machine.

### Regular updates

If you want to do updates on a regular basis, you should configure your
preferred cron system to do so.

### Playbooks

These are the essential components for doing the actual work. Playbooks are
directories with a `description.txt` and a `playbook.bash`. The latter contains
3 functions, `playbook_add()`, `playbook_sync()`, and `playbook_del()`, each
called for the `add`, `sync`, end `del` subactions respectively. Using these
functions, one can automate the setup, synchronization, or disabling of certain
components of a system.

#### Local

A local playbook is simply a directory made in `/etc/bashtard/playbooks.d` with
the two files specified earlier.

#### Remote

A remote playbook is recorded in `/etc/bashtard/playbooks.d/remotes`. This is a
space-seperated file, containing 3 columns per line, `name`, `url`, and
`branch`. When the `sync` subcommand is called, the latest commits on the
specified `branch` are pulled before calling `playbook_sync()` on them. The
structure of the actual playbook is the same as a local one.

### SSH

Bashtard comes with an `ssh` subcommand to allow the user to run any command on
all their servers. This can be useful for performing certain actions on all your
servers at once.

## Debugging and Support

For support you can email to `~tyil/bashtard@lists.sr.ht`. If you're reporting a
bug, it is recommended to include a reproduction path which is as clear as
possible. Additionally, you should include the output of the `sysinfo`
subcommand.

## License

This project is licensed under the terms of the AGPL-3.0.