Document the setup wizard

This commit is contained in:
Thomas Sileo 2019-04-22 10:52:32 +02:00
parent 116d2e3e6e
commit ac7a87f22a
3 changed files with 60 additions and 42 deletions

View file

@ -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

View file

@ -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
```
### 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...
$ make config
```
### 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

View file

@ -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__":