Installation Guide

This document provides step-by-step instructions for installing Calminer on your system. Please follow the steps below to ensure a successful installation.

Deployment Options

Calminer can be deployed using Docker containers, which simplifies the installation process and ensures consistency across different environments. The recommended deployment option is to use Docker Compose to manage the multi-container setup.

Docker Installation

Prerequisites

Before you begin, ensure that you have the following prerequisites installed on your system:

Docker
Docker Compose
Git

Steps

Clone the Repository

Open your terminal and run the following command to clone the Calminer repository:
```
git clone https://git.allucanget.biz/allucanget/calminer.git
cd calminer
```
Build and Start the Docker Containers

Run the following command to build and start the Docker containers:
```
docker compose up --build
```
This command will build the Docker images and start the containers as defined in the docker-compose.yml file.
Access the Application

Once the containers are up and running, you can access the Calminer application by navigating to http://localhost:3000 in your web browser. If you are running the application on a remote server, replace localhost with the server's IP address or domain name.
Database Initialization

The first time you run the application, the database will be initialized automatically. Ensure that the database container is running and accessible.
Seed Default Accounts and Roles

After the schema is in place, run the initial data seeding utility so the default roles and administrator account exist:
```
# activate your virtualenv first
python -m scripts.00_initial_data
```
The script reads the standard database environment variables (see below) and supports the following overrides:
- CALMINER_SEED_ADMIN_EMAIL (default admin@calminer.local)
- CALMINER_SEED_ADMIN_USERNAME (default admin)
- CALMINER_SEED_ADMIN_PASSWORD (default ChangeMe123! — change in production)
- CALMINER_SEED_ADMIN_ROLES (comma list, always includes admin)
- CALMINER_SEED_FORCE (true to rotate the admin password on every run)
You can rerun the script safely; it updates existing roles and user details without creating duplicates.
Stopping the Application

To stop the application, run the following command in the terminal:
```
docker compose down
```
This command will stop and remove the containers, networks, and volumes created by Docker Compose.

Docker Configuration

The docker-compose.yml file contains the configuration for the Calminer application, including the services, networks, and volumes. You can customize the configuration as needed to suit your deployment environment.

Environment Variables

The application uses environment variables to configure various settings. You can set these variables in a .env file in the root directory of the project. Refer to the docker-compose.yml file for a list of available environment variables and their default values.

Volumes

The application uses Docker volumes to persist data. The following volumes are defined in the docker-compose.yml file:

calminer_data: Used to persist application data.
calminer_db_data: Used to persist database data.

Ensure that these volumes are properly configured to avoid data loss during container restarts or removals.

Troubleshooting

If you encounter any issues during the installation or deployment process, refer to the following troubleshooting tips:

Check the Docker and Docker Compose logs for error messages.
Ensure that all prerequisites are installed and up to date.
Verify that the ports used by the application are not blocked by firewalls or other applications.
Consult the Calminer documentation and community forums for additional support.

3.9 KiB Raw Blame History