Getting Started with Aloha¶
This guide covers two ways to use Aloha:
- Install the
alohaPython library in an existing application. - Use the
aloha-pythonrepository as a Docker-based microservice template.
1. Install the Python Library¶
Aloha supports Python 3.10 and later. Install the base package:
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:
2. Use Aloha in an Application¶
Import only the modules your application needs. For example, the shared logger is available from aloha.logger:
To use HOCON settings, provide a resource configuration directory and load values from SETTINGS:
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:
3. Start from the Microservice Template¶
Clone the repository and enter the project:
Start and enter the containerized development environment:
From the container shell, run the sample FastAPI/Uvicorn service and tests:
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:
The Docker build can compile selected application modules with Cython. See the CLI guide and compilation reference.
Next Steps¶
- Browse the API reference.
- Learn about structured logging, database integrations, and HOCON configuration.
- Review the 12-Factor application guide for deployment practices.