Skip to main content

Task 01 — Run AquaGen API Locally

Difficulty: Beginner
Goal: Clone the AquaGen API repo, install dependencies, and get the development server running.

What you'll learn
  • How the project is structured (Flask app, blueprints, services)
  • How environment config works with Azure Key Vault / .env fallback
  • How to authenticate with Swagger UI

Prerequisites​

Before you begin, ensure you have:

  • Python 3.11
  • pip (Python package manager)
  • Git
  • Azure Account (for cloud services)
  • Virtual Environment (recommended)
System Requirements
  • OS: macOS, Linux, or Windows with WSL2
  • RAM: Minimum 4GB (8GB recommended)
  • Disk Space: At least 2GB free space

Steps​

1. Clone the repo​

git clone https://github.com/Fluxgentech/aquagenapi.git
cd aquagenapi

2. Create a virtual environment​

python -m venv .venv

# Activate on macOS/Linux:
source .venv/bin/activate

# Activate on Windows:
.venv\Scripts\activate

3. Install dependencies​

pip install -r requirements.txt
macOS Users

If you encounter errors with PDF generation libraries, install these specific versions:

pip install xhtml2pdf==0.2.13
pip install reportlab==4.0.7

4. Run the server​

export FLASK_DEBUG=1 && export FLASK_ENV=dev && flask run --host localhost --port 5001

The application will start on http://localhost:5001.

5. Open Swagger and log in​

Access the interactive Swagger docs:

To authenticate:

GET http://localhost:5001/api/user/login
username: your-username
password: your-password

The response includes a token — paste it into the Authorize button in Swagger to access protected endpoints.

Token Expiration

Access tokens expire after 4 hours. Refresh tokens last for 14 days.

Done when
  • Server starts without errors on port 5001
  • Swagger UI loads at http://localhost:5001/api/user/docs
  • You can log in and hit at least one authenticated endpoint and get data back

Troubleshooting​

Port already in use​

lsof -ti:5001 | xargs kill -9

Package installation errors​

pip install --upgrade pip
pip install -r requirements.txt

Hints​

tip
  • The entry point is app.py at the project root — not app/__init__.py.
  • Ask your team lead for local dev credentials — never commit them to the repo.