#+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 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 main.go -db ./mcias.db
#+end_src

By default, the server listens on port 8080.

*** Configuration Options

MCIAS supports the following command-line options:

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

Example with custom port:

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

** Building from Source

To build a binary:

#+begin_src bash
go build -o mcias
#+end_src

Then run the binary:

#+begin_src bash
./mcias -db ./mcias.db
#+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

** 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