Skip to content

Commit bd97f84

Browse files
romkeyromkey
committed
doc updates
1 parent 6dc3339 commit bd97f84

4 files changed

Lines changed: 122 additions & 3 deletions

File tree

‎README.md‎

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,20 @@
22

33
This repo configures a set of services that PDX Hackerspace uses to provide services for its members and for infrastructure, administration and yes, fun and entertainment.
44

5+
Hackstack uses Docker (with compose) to
6+
7+
Hackstack's priorities are:
8+
- consistency - all applications follow similar conventions in how
9+
they are configured, managed, store data and are backed up
10+
- ease of management - Hackstack is meant to be manageable by users
11+
with basic Linux knowledge and without advanced Docker or
12+
virtualization environment experience
13+
- low overhead - Hackstack is intended to minimize overhead when
14+
possible - it should be possible to operate many Hackstack services
15+
on small computers like a Raspberry Pi
16+
- ease of recovery - Hackstack is designed to make disaster recovery
17+
easy when possible
18+
519
- [Philosphy and Design](docs/design.md)
620
- [Examples](docs/examples.md)
721
- [Installation](docs/installation.md)
@@ -12,5 +26,8 @@ This repo configures a set of services that PDX Hackerspace uses to provide serv
1226

1327
## Contributing
1428

29+
Please see the [Contributing](docs/contributing.md) guide.
30+
1531
## License
1632

33+
Hackstack is released under the MIT License.

‎docs/contributing.md‎

Lines changed: 24 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -6,9 +6,31 @@ We don't intend it as any kind of ubiquitous or universal guide to server softwa
66

77
Hackstack applications all follow a set of conventions that dictate how they store data, publish network ports, use databases, are configured and backed up, and interact with one another. By following conventions the system stays manageable and organized; we know where everything lives and how it works, instead of being a haphazard collection of Docker and compose files that all do everything differently.
88

9+
## tldr;
10+
11+
1. All applications have their own Docker Compose files
12+
13+
2. Each application lives in a directory in `/opt/docker`
14+
15+
3. Each application's volumes are filesystem binds that are stored in a directory named for the application `/opt/lib`, `/opt/logs` or `/opt/run`
16+
17+
4. Unless absolutely necessary, applications do not use host networking and do not publish ports. Whenever possible, applications are exposed via `nginx-proxy-manager`
18+
19+
5. Applications are isolated on Docker networks that connect functional groups
20+
21+
6. Unless absolutely necessary, applications use the shared instances of Postgresql and Mariadb and do not spin up their own instances of them. However, applications that require Redis do use their own instance of that.
22+
23+
7. Environment variables are stored in `.env`, not in `docker-compose.yml`. Applications should provide a `.env.example` with secrets redacted.
24+
25+
8. The environment variable `BACKUP_DATABASE_URLS` in a `.env` file will allow dumps of live databases to be backed up automatically.
26+
27+
9. Applications will be automatically updated by Watchtower. For locally built applications or applications that shouldn't be updated, add the label `com.centurylinklabs.watchtower.enable=false` to the compose file.
28+
29+
10. Applications that follow these conventions will have their files and databases backed up automatically.
30+
931
## Docker Compose
1032

11-
All services are managed by Docker Compose. The service should include a docker-compose.yml file in a directory at the root of the repository.
33+
All services are managed by Docker Compose. The service should include a `docker-compose.yml` file in a directory at the root of the repository.
1234

1335
As a rule we try to allow users to customize the installation as much as possible without modifying the compose file. Obviously this isn't always possible but we strongly prefer doing so when possible. This allows the user a change to potentially be able to simply pull new versions of the hackstack to gain new applications.
1436

@@ -17,7 +39,7 @@ As a rule we try to allow users to customize the installation as much as possibl
1739
Docker Compose can specify external directories or Docker volumes to be mounted inside the container. We use a specific organization for volumes (`APPNAME` is the name of the application):
1840

1941
- any configuration data will be stored in a directory called `config` in the directory containing the `docker-compose` file
20-
- any runtime data, state information, sqlite3 databases - anything that maintains the state of the application and which must be preserved across runs - will be stored in `../../lib/APPNAME`. Applications which mingle configuration and run-time data in a way that makes it difficult to isolate them may store configuration data in this directory as well.
42+
- any runtime data, state information, Sqlite3 databases - anything that maintains the state of the application and which must be preserved across runs - will be stored in `../../lib/APPNAME`. Applications which mingle configuration and run-time data in a way that makes it difficult to isolate them may store configuration data in this directory as well.
2143
- log files go in `../../log/APPNAME`
2244
- transient runtime files, like caches or FIFOs, go in `../../run/APPNAME`
2345

‎docs/design.md‎

Lines changed: 49 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,54 @@
11
# Philosophy
22

3+
Hackstack's priorities are:
4+
- consistency
5+
- ease of maintenance
6+
- ease of disaster recovery
7+
8+
Hackstack is designed specifically for a hacker/makerspace type of
9+
environment and recognizes that the needs and resources of such an
10+
environment are very different from those of a business selling
11+
web-based services.
12+
13+
Hacker/Makerspaces are generally smallish, low resourced
14+
organizations. They:
15+
- have memberships (users) which more likely number in the hundreds
16+
rather than hundreds of thousands to millions
17+
- offer services which may reasonably be only accessible on-site
18+
- most likely do not have the resources to buy modern server hardware
19+
(and in fact may be running on scavenged or reclaimed hardware)
20+
- most likely do not have the resources to have an on call tech
21+
support or IT staff but rather a few volunteers that keep things
22+
chugging along
23+
24+
### Anti-goals
25+
26+
Recognizing these conditions helps us understand some
27+
anti-goals. These spaces do not need services that:
28+
- scale
29+
- migrate easily or transparently between nodes
30+
and they do not need the overhead of running and maintaining systems
31+
that offer those as primary features.
32+
33+
### Hardware
34+
35+
Because Hacker/Makerspaces often use older hardware they are subject
36+
to a higher likelihood of hardware failure than businesses would
37+
generally anticipate while having fewer resources to manage
38+
failures. This dictates that overall design favor ease of disaster
39+
recovery and keeping resource requirements minimal.
40+
41+
### Consistency
42+
43+
There is little consistency to how applications are offered online
44+
using Docker compose files. Naming, port allocation, filesystem use
45+
all vary tremendously. From a maintenance perspective having to figure
46+
out how each individual application is set up can be a collosal
47+
headache when they're all different. Therefore Hackstack provides a
48+
set of guidelines as to how applications will be installed, similar to
49+
how Linux has done for decades. Once a maintainer is familiar with
50+
them they can easily inspect and manage any Hackstack application.
51+
352
## Underlying System
453

554
Keep the underlying system hosting the servers as clean and unpolluted

‎docs/installation.md‎

Lines changed: 32 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,35 @@
11
## Installation
22

3-
First, install [Docker Engine](), [Docker CLI]() and [Docker Compose]() on your system.
3+
Hackstack is designed to require minimal additional software installed
4+
on a stock Linux server. Whenever possible dependencies are isolated
5+
within Docker containers. PDX Hackerspace runs Hackstack on a Debian
6+
installation. Unless you absolutely require a GUI we recommend saving
7+
the resources that it would take and just running a "server"-stye
8+
system with no graphic user interface.
49

10+
First, install [Docker CLI](https://docs.docker.com/engine/install/)
11+
and if needed Docker Compose on your system.
12+
13+
Then make sure `git` is installed. On Debian-style systems you can do
14+
this with:
15+
```
16+
sudo apt update
17+
sudo apt install git
18+
```
19+
20+
Then clone the Hackstack repo, preferably into `/opt/docker`:
21+
```
22+
git clone https://github.com/romkey/pdxhackerspace-hackstack
23+
```
24+
25+
At that point you can begin spinning up services. Start with
26+
foundational services like `dnsmasq`, `postgresql` and `mariadb` if
27+
you need them. For each service you'll want to edit its `.env` file if
28+
there is one and then bring up its Docker container. For instance, for
29+
`calibre-web` you would:
30+
```
31+
cd /opt/docker/calibre
32+
cp .env.example .env
33+
vi .env
34+
docker compose up -d
35+
```

0 commit comments

Comments
 (0)