capsul-flask/docs/local-set-up.md

# How to run Capsul locally

## <a name="manually"></a>Manually

Ensure you have the pre-requisites for the psycopg Postgres database adapter package:

```sh
sudo apt install gcc python3-dev libpq-dev
pg_config --version
```

Ensure you have the wonderful `pipenv` python package management and virtual environment cli:

```sh
sudo apt install pipenv
```

Create python virtual environment and install packages:

```sh
pipenv install
```

Install and configure Postgres:

```sh
sudo apt install -y postgresql

sudo -u postgres psql 
psql (15.5 (Debian 15.5-0+deb12u1))
Type "help" for help.

postgres=# create database "capsul-flask";
CREATE DATABASE
postgres=# create user "capsul-flask" WITH PASSWORD 'blah';
CREATE ROLE
postgres=# alter database "capsul-flask" owner to "capsul-flask";
ALTER DATABASE
postgres=# grant all privileges on database "capsul-flask" to "capsul-flask";
GRANT
postgres=# quit
```

> NOTE: you can also use docker for this if you wish. See the postgres docker hub page for more details.
> `docker run --rm -it -e POSTGRES_PASSWORD=dev -p 5432:5432 postgres`

Run the app 

```sh
pipenv run flask run
```

or, using Gunicorn:

```sh
pipenv run gunicorn --bind 127.0.0.1:5000 -k gevent --worker-connections 1000 app:app
```

Note that by default when running locally, the `SPOKE_MODEL` is set to `mock`, meaning that it won't actually try to spawn vms.

## Crediting your account

Once you log in for the first time, you will want to give yourself some free capsulbux so you can create fake capsuls for testing. 

```sh
pipenv run flask cli sql -c "INSERT INTO payments (email, dollars) VALUES ('<your email address here>', 20.00)"
```

## Running scheduled tasks:

```sh
pipenv run flask cli cron-task
```

## <a name="docker_compose"></a>Run locally with docker-compose

If you have Docker and Docker-Compose installed, you can use the
`3wordchant/capsul-flask` Docker image to launch capsul-flask, and a Postgres
database server, for you:

```sh
docker-compose up
```

`capsul-flask` will read settings from your `.env` file as usual; you can set any of the options mentioned in the [configuration documentation](./configuration.md).