From ac7a87f22a5b22f0a20d3d9e588f2fc32c095af5 Mon Sep 17 00:00:00 2001 From: Thomas Sileo Date: Mon, 22 Apr 2019 10:52:32 +0200 Subject: [PATCH] Document the setup wizard --- Makefile | 24 ++++++++++++------- README.md | 53 +++++++++++++++++++----------------------- setup_wizard/wizard.py | 25 ++++++++++++++++---- 3 files changed, 60 insertions(+), 42 deletions(-) diff --git a/Makefile b/Makefile index 6870cf1..60bc7c6 100644 --- a/Makefile +++ b/Makefile @@ -1,12 +1,17 @@ PYTHON=python +SETUP_WIZARD_IMAGE=microblogpub-setup-wizard:latest +PWD=$(shell pwd) -password: - $(PYTHON) -c "import bcrypt; from getpass import getpass; print(bcrypt.hashpw(getpass().encode('utf-8'), bcrypt.gensalt()).decode('utf-8'))" - -docker: - mypy . --ignore-missing-imports - docker build . -t microblogpub:latest +.PHONY: config +config: + # Build the container for the setup wizard on-the-fly + cd setup_wizard && docker build . -t $(SETUP_WIZARD_IMAGE) + # Run and remove instantly + -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 diff --git a/README.md b/README.md index 0640066..b36465f 100644 --- a/README.md +++ b/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 -$ cp -r config/me.sample.yml config/me.yml +$ make config ``` -### Configuration - -```shell -$ make password -Password: -$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="" 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="" flask run -p 5005 --with-threads ``` ## API diff --git a/setup_wizard/wizard.py b/setup_wizard/wizard.py index 16be68a..5b5cd05 100644 --- a/setup_wizard/wizard.py +++ b/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__":