First initial version of provsn docs

Author: victorb

README.md

@@ -13,16 +13,6 @@
 - Known issues
 - Common tasks
 
-TODO before @lgierth vacation:
-
-- secrets submodule
-- make parallelism less awkward
-- fix unwanted `./provsn` parallelism
-- make sure `./provsn help` is up-to-date
-- migrate ansible/{common,ipfs,ipfs_gateway,nginx}
-  - cjdns,metrics,node_exporter,pinbot remain todo
-- migrate peering script
-
 ### Introduction
 
 This repository contains the technical infrastructure of the IPFS community.
@@ -42,7 +32,7 @@ Infrastructure that isn't contained here:
 
 ### Getting started
 
-We use an experimental tool called Provsn to maintain the setup of hosts and services.
+We use a tool called Provsn to maintain the setup of hosts and services.
 The fundamental principle of Provsn is that hosts are in a certain state,
 and units of code are run to transition into a different state.
 

ansible/README.md

@@ -1,3 +1,9 @@
+## DEPRECATED
+
+We're trying to move away from ansible and this document is just here for history.
+
+We should try to migrate this documentation to provsn
+
 # solarnet
 
 - [Overview](#overview)

base/README.md

@@ -0,0 +1,3 @@
+## Unit - Base
+
+This is the base unit. It installs required packages and also installs ssh-keys.

docker/README.md

@@ -0,0 +1,5 @@
+## Unit - Docker
+
+Installs docker on a machine.
+
+TODO: Difference between getdocker.sh and install.sh? Should just be install.sh

ipfs/README.md

@@ -0,0 +1,5 @@
+## Unit - IPFS
+
+The IPFS unit, responsible for installing go-ipfs and setup the configuration.
+
+Starts IPFS in a docker container.

provsn.md

@@ -0,0 +1,90 @@
+## provsn
+
+provsn is our homemade provisioning tool.
+
+## Requirements
+
+* parallel
+* bash
+* ssh
+* jq
+* readlink
+* dirname
+* find
+* xargs
+* sed
+* awk
+* uniq
+* sort
+
+## Concepts
+
+provsn is a simple and nimble little tool, we just have a few concepts you need
+to understand to be able to use it and contribute.
+
+### Host
+
+A host is a computer that you have ssh access to and want to manage. They
+are all mapped in `env.sh` in the root directory.
+
+Typically looks something like this:
+
+```sh
+# digitalocean-sfo1
+pluto_ssh="[email protected]"
+pluto_units=(${baseunits[@]} ${gatewayunits[@]})
+```
+
+### Unit
+
+A unit is something that you can install and manage on a host. A unit needs to
+have at least a `env.sh` file in it's directory. Typical structure:
+
+```
+nginx
+├── 451.html
+├── build.sh
+├── env.sh
+├── install.sh
+└── nginx.conf
+```
+
+Both `451.html` and `nginx.conf` is unique for the nginx unit.
+
+`env.sh` sets environment variables for this unit, in this case setting the nginx
+version we want to use.
+
+`build.sh` contains setup instructions for our `install.sh` script. In nginx case,
+we copy `451.html` and `nginx.conf` to `out/` and then also create a `out/docker.opts`
+file with our arguments to docker.
+
+`install.sh` is the script that actually installs nginx on our hosts. We now have
+access to our files in `out/` on our host, so we copy them to the right place and
+compare if anything changed. If it did, we make sure to restart the docker container.
+
+## How to use provsn
+
+provsn is a simple bash tool that should work on all platforms. To run, it simply
+execute the script.
+
+```sh
+./provsn <command> <@args>
+```
+
+## Common Tasks
+
+### Gathering ipfs debug info
+
+Grab the logs since `1 minute ago` on `pluto`
+
+```sh
+./provsn exec pluto "docker logs --since 1m ipfs"
+```
+
+### Updating IPFS on hosts
+
+### Deploying a website
+
+### Adding a root user
+
+### Adding hashes to the blocklist