Skip to content

Getting Started with Aloha

This guide covers two ways to use Aloha:

  1. Install the aloha Python library in an existing application.
  2. Use the aloha-python repository as a Docker-based microservice template.

1. Install the Python Library

Aloha supports Python 3.10 and later. Install the base package:

python -m pip install aloha

Install extras for optional capabilities:

python -m pip install "aloha[service]"  # FastAPI and Uvicorn support
python -m pip install "aloha[db]"       # Database integrations
python -m pip install "aloha[all]"      # All optional dependencies

Other extras include aio for asynchronous database drivers, build for Cython compilation, stream for Kafka clients, data and report for data/reporting tools, and test and docs for development.

Verify the installation:

aloha info

2. Use Aloha in an Application

Import only the modules your application needs. For example, the shared logger is available from aloha.logger:

from aloha.logger import LOG

LOG.info("Application started")

To use HOCON settings, provide a resource configuration directory and load values from SETTINGS:

from aloha.settings import SETTINGS

config_settings = SETTINGS.config

By default, Aloha looks for configuration under resource/config/ relative to the current working directory. PROFILE_ENV, FILES_CONFIG, DIR_RESOURCE, and DIR_CONFIG can be used to select profiles and locations. See the configuration guide for details.

The aloha start command can run a module whose main() function starts your application:

aloha start your_package.main

3. Start from the Microservice Template

Clone the repository and enter the project:

git clone https://github.com/LabNow-ai/aloha-python.git
cd aloha-python

Start and enter the containerized development environment:

./tool/cicd/run-dev.sh up
./tool/cicd/run-dev.sh enter

From the container shell, run the sample FastAPI/Uvicorn service and tests:

cd /workspace/src
python3 main.py app_common.main
pytest ./

The sample application lives in src/app_common/; service configuration and profiles live in src/resource/config/. Adapt these to your application. See the development guide for container commands and configuration guide for HOCON setup.

4. Build a Production Image

From the repository root, build the example Docker image:

source tool/tool.sh
build_image app_common latest src/app-demo.Dockerfile

The Docker build can compile selected application modules with Cython. See the CLI guide and compilation reference.

Next Steps