mcias/docs/installation.org

#+title: MCIAS Installation and Usage Guide
#+created: <2025-05-09 Fri 13:42>

* MCIAS Installation and Usage Guide

** Prerequisites

Before installing MCIAS, ensure you have the following prerequisites:

- Go 1.23 or later
- SQLite3
- golangci-lint (for development)

** Installation

*** Clone the Repository

#+begin_src bash
git clone git.wntrmute.dev/kyle/mcias
cd mcias
#+end_src

*** Install Dependencies

#+begin_src bash
go mod download
#+end_src

*** Initialize the Database

MCIAS uses SQLite for data storage. To initialize the database:

#+begin_src bash
go run cmd/mcias/main.go init --db ./mcias.db
#+end_src

This command creates a new SQLite database file and initializes it with the schema defined in =schema.sql=.

** Running the Server

*** Basic Usage

To start the MCIAS server with default settings:

#+begin_src bash
go run cmd/mcias/main.go server --db ./mcias.db
#+end_src

By default, the server listens on port 8080.

*** Configuration Options

MCIAS supports the following command-line options for the server:

- =--db <path>=: Path to the SQLite database file (default: =mcias.db=)
- =--addr <address>=: Address to listen on (default: =:8080=)

Example with custom port:

#+begin_src bash
go run cmd/mcias/main.go server --db ./mcias.db --addr :9000
#+end_src

** Managing Users and Authentication

*** Adding a New User

To add a new user to the system:

#+begin_src bash
go run cmd/mcias/main.go user add --username <username> --password <password>
#+end_src

*** Managing TOTP Authentication

To enable TOTP for a user:

#+begin_src bash
go run cmd/mcias/main.go totp enable --username <username>
#+end_src

This will generate a TOTP secret for the user and display it. The user should save this secret in their authenticator app.

To add a TOTP token with QR code generation:

#+begin_src bash
go run cmd/mcias/main.go totp add --username <username> --qr-output <path/to/qrcode.png>
#+end_src

To validate a TOTP code:

#+begin_src bash
go run cmd/mcias/main.go totp validate --username <username> --code <totp_code>
#+end_src

** Building from Source

To build the server binary:

#+begin_src bash
cd cmd/mcias
go build -o mcias
#+end_src

Then run the binary:

#+begin_src bash
./mcias server --db ./mcias.db
#+end_src

To build the client binary:

#+begin_src bash
cd cmd/mcias-client
go build -o mcias-client
#+end_src

** Development

*** Running Tests

To run all tests:

#+begin_src bash
go test ./...
#+end_src

*** Linting

To run the linter:

#+begin_src bash
golangci-lint run
#+end_src

** Using the API

*** Authentication with Password

To authenticate a user with a password:

#+begin_src bash
curl -X POST http://localhost:8080/v1/login/password \
  -H "Content-Type: application/json" \
  -d '{
    "version": "v1",
    "login": {
      "user": "username",
      "password": "password"
    }
  }'
#+end_src

*** Authentication with Token

To authenticate a user with a token:

#+begin_src bash
curl -X POST http://localhost:8080/v1/login/token \
  -H "Content-Type: application/json" \
  -d '{
    "version": "v1",
    "login": {
      "user": "username",
      "token": "your_token"
    }
  }'
#+end_src

*** Authentication with TOTP

To authenticate a user with a password and TOTP code:

#+begin_src bash
curl -X POST http://localhost:8080/v1/login/totp \
  -H "Content-Type: application/json" \
  -d '{
    "version": "v1",
    "login": {
      "user": "username",
      "password": "password",
      "totp": "123456"
    }
  }'
#+end_src

*** Retrieving Database Credentials

To retrieve database credentials:

#+begin_src bash
curl -X GET "http://localhost:8080/v1/database/credentials?username=username" \
  -H "Authorization: Bearer your_token"
#+end_src

** Troubleshooting

*** Common Issues

1. *Database errors*: Ensure the database file exists and has the correct permissions.
   #+begin_src bash
   # Check permissions
   ls -l mcias.db
   # Fix permissions if needed
   chmod 644 mcias.db
   #+end_src

2. *Port already in use*: If the port is already in use, specify a different port with the =-addr= flag.
   #+begin_src bash
   go run main.go -db ./mcias.db -addr :8081
   #+end_src

3. *Authentication failures*: Ensure you're using the correct username and password/token.

*** Logging

MCIAS logs to stdout by default. To capture logs to a file:

#+begin_src bash
go run main.go -db ./mcias.db > mcias.log 2>&1
#+end_src

** Security Best Practices

1. *Production Deployment*:
   - Use HTTPS in production
   - Set up proper firewall rules
   - Run the service with minimal privileges

2. *Database Security*:
   - Regularly backup the database
   - Restrict file permissions on the database file
   - Consider encrypting the database file at rest

3. *User Management*:
   - Implement strong password policies
   - Regularly rotate tokens
   - Monitor for suspicious authentication attempts