Ecodev App¶

This is the cornerstone of Ecoact CDA team Open source contribution: ecodev-app.

What you can get out of the box 😊

Heavily inspired by Tiangolo full-stack FastAPI template, we wanted to provide something on the same vein but purely based on python. Plus when we started working on it, Tiangolo's work was not yet based on SQLModel, only on SQL Alchemy.

That is why we use Dash as our frontend tool, in order to only use python as programming language, a thing quite convenient these days.

In this part of the documentation, you will find details on what is inside ecodev-app.

We assume here that you have already read and/or have been redirected from the setup from scratch part of the doc, meaning you have an operational db.

Usage¶

1. New repository¶

First create a <new-repository> in your GitHub, then follow these commands, replacing any mention of <new-repository>, with your repo name:

# Create new folder where you would like your repo to be located on your machine
mkdir <new-repository>; cd <new-repository>

# Make a bare clone of this repository
git clone https://github.com/SE-Sustainability-OSS/ecodev-app

# Move files to parent directory
cd .. ; mv <new-repository>/ecodev-app/* <new-repository>/

# Delete remaining ecodev-app files
cd <new-repository> ; rm -rf ecodev-app/

# Remove git file
rm -rf .git

# Create new .git file (and optionally rename master to main)
git init ; git branch -M main

# Add new remote
git remote add origin https://github.com/<user>/<new-repository>

2. Replace name¶

Search for and replace any references to ecodev-app and ecodev_app within the repo, with your own app name.

docker-compose.yml
docker-compose.override.yml
Makefile

Warning

Do keep the respective - and _ used throughout

3. Update Readme¶

Update this README.md with your own. A template is provided in README-template.md

Feel free to remove any other markdown file (e.g. SECURITY.md, CODE_OF_CONDUCT.md, etc.) that are not applicable._

4. First commit¶

Once done, create your first commit and push to your new repo, as you would normally do.

git add . ; git commit -m 'Initial commit'
git push origin main

$ git add . 
$ git commit -m 'Initial commit'
$ git push origin main
---> 100%
Successfully initialized ecodev-app!

Run¶

To run your app, follow the steps below (also available in the README-template.md file)

1. Env file¶

Create an .env file and save it under the application's root folder. It must contain the following (you have an env_template to help you):

# App name
app_name= template # Name of the app. Will appear on the app header.

# API app
app_port=8000 # API app port number. Remove this entry in production
fastapi_url= # API app web url. Fill only in production.

# Dash app
dash_app_port=8071 # Dash app port number. Remove this entry in production
dash_url= # Dash app web url.  Fill only in production.

# Jupyter app
jupyter_port=5000 # Jupyter notebook port number. Remove this entry in production

# Database access
db_port=5432 # Database port number
db_host=db # Database server name
db_name=db # Database name
db_username=user # Database login username. Change to a real username.
db_password=password # Database login password. Change to a secured password.

# Hashing secrets
secret_key=azertyuiopqdfghjklmwxcvbn134567890azertyuiopqsdfghjklmwxcvbn1234567890 # App secret key (for hashing purposed)
algorithm=HS256 # Password hashing algorithm

# Other
access_token_expire_minutes=1440 # App JWT access token expiry duration

# App mailbox
email_sender= # Mailbox email address. Put to the real email sender
email_password= # Mailbox password. Put to the real email sender password
email_smtp= # Mailbox SMTP (like smtp.gmail.com or mail.outlook.com). Put your smtp provider here

# gunicorn/uvicorn setup
gunicorn_setup=false # Should be True in production. Simpler to only with uvicorn for local dev
debug=false # Put to true if you want to be in dash debug mode

2. Setup pre-commits¶

Run make setup to install the pre-commits

$ make setup
---> 100%
Pre-commit installed!

3. Build Docker image¶

Build the docker image

$ make dev-build
---> 100%
ecodev-app image built!

4. Setup pgadmin¶

Open your local PGAdmin and login using the admin credentials.

⚠️ You may encounter login issues if using Firefox browser.

5. db connect¶

Connect to the database server using the admin credentials

6. Create new db¶

Create a new database <YOUR_DB_NAME>_db, as per your .env file (db) in the example.

7. Create user¶

Add a user.json file under data, if you'd like to initialise a few users. It should contain:

[
    {
        "id": null,
        "user": "user_name",
        "password": "hashed_password",
        "permission": "permission_level",
        "client": "project_name",
        "application": "application_name"
    }
]

8. Actually launch the container! 😊¶

Run the docker container

$ docker compose up -d
---> 100%
Successfully launched ecodev-app!

The app should be running under http://localhost: :

To check for any issues, you can check the logs with:

docker logs <YOUR_APP_CONTAINER_NAME> --tail=100 -f

$ docker logs ecodev-app --tail=100 -f
some logs

Use Ctrl+C to exit the logs