103 lines
3.9 KiB
Markdown
103 lines
3.9 KiB
Markdown
# 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
|
|
|
|
1. **Clone the Repository**
|
|
|
|
Open your terminal and run the following command to clone the Calminer repository:
|
|
|
|
```bash
|
|
git clone https://git.allucanget.biz/allucanget/calminer.git
|
|
cd calminer
|
|
```
|
|
|
|
2. **Build and Start the Docker Containers**
|
|
|
|
Run the following command to build and start the Docker containers:
|
|
|
|
```bash
|
|
docker compose up --build
|
|
```
|
|
|
|
This command will build the Docker images and start the containers as defined in the `docker-compose.yml` file.
|
|
|
|
3. **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.
|
|
|
|
4. **Database Initialization**
|
|
|
|
The first time you run the application, the database will be initialized automatically. Ensure that the database container is running and accessible.
|
|
|
|
5. **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:
|
|
|
|
```bash
|
|
# 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.
|
|
|
|
6. **Stopping the Application**
|
|
|
|
To stop the application, run the following command in the terminal:
|
|
|
|
```bash
|
|
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.
|