Document the setup wizard

Makefile

@@ -1,12 +1,17 @@
 PYTHON=python
+SETUP_WIZARD_IMAGE=microblogpub-setup-wizard:latest
+PWD=$(shell pwd)
 
-password:
+.PHONY: config
-	$(PYTHON) -c "import bcrypt; from getpass import getpass; print(bcrypt.hashpw(getpass().encode('utf-8'), bcrypt.gensalt()).decode('utf-8'))"
+config:
-
+	# Build the container for the setup wizard on-the-fly
-docker:
+	cd setup_wizard && docker build . -t $(SETUP_WIZARD_IMAGE)
-	mypy . --ignore-missing-imports
+	# Run and remove instantly
-	docker build . -t microblogpub:latest
+	-docker run --rm -it --volume $(PWD):/app/out $(SETUP_WIZARD_IMAGE)
+	# Finally, remove the tagged image
+	docker rmi $(SETUP_WIZARD_IMAGE)
 
+.PHONY: reload-fed
 reload-fed:
 	docker build . -t microblogpub:latest
 	docker-compose -p instance2 -f docker-compose-tests.yml stop
@@ -14,14 +19,17 @@ reload-fed:
 	WEB_PORT=5006 CONFIG_DIR=./tests/fixtures/instance1/config docker-compose -p instance1 -f docker-compose-tests.yml up -d --force-recreate --build
 	WEB_PORT=5007 CONFIG_DIR=./tests/fixtures/instance2/config docker-compose -p instance2 -f docker-compose-tests.yml up -d --force-recreate --build
 
+.PHONY: poussetaches
 poussetaches:
 	git clone https://github.com/tsileo/poussetaches.git pt && cd pt && docker build . -t poussetaches:latest && cd - && rm -rf pt
 
+.PHONY: reload-dev
 reload-dev:
-	# docker build . -t microblogpub:latest
+	docker build . -t microblogpub:latest
 	docker-compose -f docker-compose-dev.yml up -d --force-recreate
 
-update:
+.PHONY: run
+run:
 	git pull
 	docker build . -t microblogpub:latest
 	docker-compose stop

README.md

@@ -55,60 +55,55 @@ Getting closer to a stable release, it should be the "last" migration.
 
 ## ActivityPub
 
-microblog.pub implements an [ActivityPub](http://activitypub.rocks/) server, it implements both the client to server API and the federated server to server API.
+_microblog.pub_ implements an [ActivityPub](http://activitypub.rocks/) server, it implements both the client to server API and the federated server to server API.
 
 Activities are verified using HTTP Signatures or by fetching the content on the remote server directly.
 
-## Running your instance
+## User Guide
+
+The easiest and recommended way to run _microblog.pub_ in production is to use the provided docker-compose config.
+
+First install [Docker](https://docs.docker.com/install/) and [Docker Compose](https://docs.docker.com/compose/install/).
+It's the only requirements, Python is not needed on the host system.
+
+Note that all the generated data (config included) will be stored on the host (i.e. not in Docker) in `config/` and `data/`.
+
 
 ### Installation
 
 ```shell
 $ git clone https://github.com/tsileo/microblog.pub
 $ cd microblog.pub
-$ pip install -r requirements.txt
+$ make config
-$ cp -r config/me.sample.yml config/me.yml
 ``` 
 
-### Configuration
-
-```shell
-$ make password
-Password: <enter a password; nothing will show on screen>
-$2b$12$iW497g...
-```
-
-Edit `config/me.yml` to add the above-generated password, like so:
-
-```
-username: 'username'
-name: 'Your Name'
-icon_url: 'https://you-avatar-url'
-domain: 'your-domain.tld'
-summary: 'your summary'
-https: true
-pass: $2b$12$iW497g...
-```
-
 ### Deployment
 
+To spawn the docker-compose project (running this command will also update _microblog.pub_ to latest and restart the project it it's already running):
+
 ```shell
-$ make update
+$ make run
 ```
 
+### Backup
+
+The easiest way to backup all of your data is to backup the `microblog.pub/` directory directly (that's what I do and I have been able to restore super easily).
+It should be safe to copy the directory while the docker-compose is running.
+
 ## Development
 
-The most convenient way to hack on microblog.pub is to run the server locally, and run
+The project requires Python3.7+.
 
+The most convenient way to hack on _microblog.pub_ is to run the Python server on the host directly, and evetything else in Docker.
 
 ```shell
-# One-time setup
+# One-time setup (in a new virtual env)
 $ pip install -r requirements.txt
 # Start MongoDB and poussetaches
 $ make poussetaches
-$ env POUSSETACHES_AUTH_KEY="SetAnyPasswordHere" docker-compose -f docker-compose-dev.yml up -d
+$ env POUSSETACHES_AUTH_KEY="<secret-key>" docker-compose -f docker-compose-dev.yml up -d
 # Run the server locally
-$ FLASK_DEBUG=1 MICROBLOGPUB_DEBUG=1 FLASK_APP=app.py POUSSETACHES_AUTH_KEY="SetAnyPasswordHere" flask run -p 5005 --with-threads
+$ FLASK_DEBUG=1 MICROBLOGPUB_DEBUG=1 FLASK_APP=app.py POUSSETACHES_AUTH_KEY="<secret-key>" flask run -p 5005 --with-threads
 ```
 
 ## API

setup_wizard/wizard.py

@@ -12,6 +12,16 @@ from prompt_toolkit import prompt
 def main():
     print("Welcome to microblog.pub setup wizard\n")
 
+    config_file = Path("/app/out/config/me.yml")
+    env_file = Path("/app/out/.env")
+
+    if config_file.exists() or env_file.exists():
+        # Spit out the relative path for the "config artifacts"
+        config_file = "config/me.yml"
+        env_file = ".env"
+        print(f"Existing setup detected, please delete {config_file} and/or {env_file} before restarting the wizard")
+        sys.exit(2)
+
     dat = {}
     print("Your identity will be @{username}@{domain}")
     dat["domain"] = prompt("domain: ")
@@ -42,10 +52,11 @@ def main():
     out = ""
     for k, v in dat.items():
         out += f"{k}: {v!r}\n"
-    print(out)
-    print()
 
-    env_file = {
+    with config_file.open("w") as f:
+        f.write(out)
+
+    env = {
         "WEB_PORT": 5005,
         "CONFIG_DIR": "./config",
         "DATA_DIR": "./data",
@@ -54,10 +65,14 @@ def main():
     }
 
     out2 = ""
-    for k, v in env_file.items():
+    for k, v in env.items():
         out2 += f"{k}={v}\n"
 
-    print(out2)
+    with env_file.open("w") as f:
+        f.write(out2)
+
+    print("Done")
+    sys.exit(0)
 
 
 if __name__ == "__main__":