capsul-flask/README.md

# capsul-flask

![screenshot of capsul.org home page](./docs/capsul.webp)

Python Flask web application implementing user accounts, payment, and virtual machine management for a smol "virtual machine (vm) as a service" aka "cloud compute" provider.  Originally developed by [Cyberia Computer Club](https://cyberia.club) for https://capsul.org

`capsul-flask` integrates with [Stripe](https://stripe.com/) as a credit card processor, and [BTCPay Server](https://github.com/btcpayserver/btcpayserver-docker) as a cryptocurrency payment processor.

`capsul-flask` invokes [shell-scripts](./capsulflask/shell_scripts/) to create/manage [libvirt/qemu](https://www.libvirt.org/manpages/virsh.html) vms, and it depends on `dnsmasq` to act as the DHCP server for the vms.

`capsul-flask` has a ["hub and spoke" architecture](./architecture.md). The "Hub" runs the web application and talks to the Postrges database, while the "Spoke"(s) are responsible for creating/managing virtual machines. In this way, capsul can be scaled to span more than one machine. One instance of the capsul-flask application can run in both hub mode and spoke mode at the same time, however there must only be one instance of the app running in "Hub" mode at any given time.

## Quickstart (run capsul-flask on your computer in development mode)

```
# get an instance of postgres running locally on port 5432
# (you don't have to use docker, but we thought this might be the easiest for a how-to example)
docker run --rm -it -e POSTGRES_PASSWORD=dev -p 5432:5432 postgres &

# install dependencies 
sudo apt install pipenv python3-dev libpq-dev

# download and run
git clone https://giit.cyberia.club/~forest/capsul-flask
cd capsul-flask
pipenv install
pipenv run flask run
```

Interested in learning more? How about a trip to the the `docs/` folder:

- [**Setting up `capsul-flask` locally**](./docs/local-set-up.md)
  - [Manually](./docs/local-set-up.md#manually)
  - [With docker-compose](./docs/local-set-up.md#docker_compose)
- [**Configuring `capsul-flask`**](./docs/configuration.md)
  - [Example configuration from capsul.org (production)](./docs/configuration.md#example)
  - [Configuration-type-stuff that lives in the database ](./docs/configuration.md#config_that_lives_in_db)
  - [Loading variables from files (docker secrets)](./docs/configuration.md#docker_secrets)
- [**`capsul-flask`'s relationship to its Database Server**](./docs/database.md)
  - [Database schema management (schema versions)](./docs/database.md#schema_management)
  - [Running manual database queries](./docs/database.md#manual_queries)
- [**`capsul-flask`'s hub-and-spoke architecture**](./docs/architecture.md)
- [**Running the automated tests**](./docs/testing.md)
- [**Deploying capsul-flask on a server**](./docs/deployment.md)
  - [Installing prerequisites for Spoke Mode](./docs/deployment.md#spoke_mode_prerequisites)
  - [Deploying capsul-flask manually](./docs/deployment.md#deploy_manually)
  - [Deploying capsul-flask with coop-cloud's docker-swarm configuration](./docs/deployment.md#coop_cloud_docker)
  - [Deploying capsul-flask with coop-cloud's `abra` deployment tool](./docs/deployment.md#coop_cloud_abra)
- [**Accepting cryptocurrency payments with BTCPay Server**](./docs/btcpay.md)
  - [Setting up the BTCPAY_PRIVATE_KEY](./docs/btcpay.md#BTCPAY_PRIVATE_KEY)
  - [Testing cryptocurrency payments](./docs/btcpay.md#testing)
  - [Sequence diagram explaining how BTC payment process works (how we accept 0-confirmation transactions 😀)](./docs/btcpay.md#0_conf_diagram)