Skip to content

SUSE/aimaas

Folders and files

NameName
Last commit message
Last commit date

Latest commit

ca9b4ec · Oct 15, 2024
Jan 19, 2024
Sep 3, 2024
Oct 15, 2024
Oct 14, 2021
Nov 30, 2021
Oct 14, 2021
Oct 18, 2021
Jul 22, 2024
Jul 22, 2024
Jan 19, 2024
Feb 6, 2023

Repository files navigation

Abstract Information Management and Authority Service (aimaas)

aimaas aims to be a central authoritative web service for information management. Main aspects in (future) development are:

  • EAV data model
  • Modular architecture
  • Easy to use interfaces for humans (WebUI) and machines (API)
  • Role-based permission management
  • Traceability of information changes

For more details on aimaas see: Philosophy & Architecture.

Status

This project is currently under active development.

Getting started

We assume that interested parties are familiar with Python, JavaScript, FastAPI and NodeJs.

Setup

In a nutshell, these are the steps to set up a development environment:

  1. Install PostgreSQL.
  2. Create a database.
  3. Backend
    1. Create a file with environment variable definitions (See config.py for which variables are available/required).
    2. Create a Python virtualenv (Our suggestion: Python 3.12).
    3. Install Python dependencies with pip.
    4. Run database migrations: alembic upgrade head.
  4. Frontend
    1. Install npm (and nodejs, our suggestion: v20).
    2. Install JS dependencies with npm install.

Updating NPM packages

The safe way to update packages is to run:

npm update

If you want to upgrade more aggressively (i.e. potentially introduce breaking changes) you can consider something like this:

npm install ---no-save npm-check-updates
ncu --upgrade
npm install

Running development servers

Backend

Having set up the Python backend as described you should now be able to run the backend with this command:

uvicorn backend.main:app --reload  # --env-file <path_to_your_envfile>

Note: The --env-file argument is not required, if your env. file is stored in the project root directory.

This will run the backend on localhost:8000.

Frontend

Having set up the NodeJS frontend as described you should now be able to run the frontend with this command:

cd frontend
npm run dev

This will run the frontend on localhost:8080.

Note: The dev server is configured to proxy API requests to localhost:8000 by default. If your backend development server is listening somewhere else, make sure to adjust the proxy target in vite.config.js!

Building production images

In order to build a production-ready container images you can simply run:

make all

The resulting images can be started like this:

docker run \
  -d \                                 # Demonize
  --restart unless-stopped \           # Automatically restart
  --name aimaas_ui \                   # Easy to remember name
  aimaas-ui:latest \                   # Our container image

docker run \
  -d \                                 # Demonize
  --restart unless-stopped \           # Automatically restart
  --env-file <path_to_your_envfile> \  # Use the config
  --name aimaas_api \                  # Easy to remember name
  aimaas-api:latest \                  # Our container image
  --workers 4                          # Parameters for `uvicorn`
  --root_path /api

Caveat: This obviously requires that make and docker are installed.

Caveat: A central assumption is, that the backend is reachable via the same base URL as the frontend, e.g. if the frontend is available at http://example.com/, the backend is expected at http://example.com/api/. For the development environment a reverse proxy is pre-configured. On production, this needs to be handled explicitly!

Cheat Sheet

This is a collection of helpful links:

Contributing

Right now anyone can contribute by defining requirements or submitting pull requests.