Core implementation written with Junie.

docs/installation.md

@@ -0,0 +1,170 @@
+# 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
+
+```bash
+git clone git.wntrmute.dev/kyle/mcias
+cd mcias
+```
+
+### Install Dependencies
+
+```bash
+go mod download
+```
+
+### Initialize the Database
+
+MCIAS uses SQLite for data storage. To initialize the database:
+
+```bash
+go run main.go -init -db ./mcias.db
+```
+
+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:
+
+```bash
+go run main.go -db ./mcias.db
+```
+
+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:
+
+```bash
+go run main.go -db ./mcias.db -addr :9000
+```
+
+## Building from Source
+
+To build a binary:
+
+```bash
+go build -o mcias
+```
+
+Then run the binary:
+
+```bash
+./mcias -db ./mcias.db
+```
+
+## Development
+
+### Running Tests
+
+To run all tests:
+
+```bash
+go test ./...
+```
+
+### Linting
+
+To run the linter:
+
+```bash
+golangci-lint run
+```
+
+## Using the API
+
+### Authentication with Password
+
+To authenticate a user with a password:
+
+```bash
+curl -X POST http://localhost:8080/v1/login/password \
+  -H "Content-Type: application/json" \
+  -d '{
+    "version": "v1",
+    "login": {
+      "user": "username",
+      "password": "password"
+    }
+  }'
+```
+
+### Authentication with Token
+
+To authenticate a user with a token:
+
+```bash
+curl -X POST http://localhost:8080/v1/login/token \
+  -H "Content-Type: application/json" \
+  -d '{
+    "version": "v1",
+    "login": {
+      "user": "username",
+      "token": "your_token"
+    }
+  }'
+```
+
+## Troubleshooting
+
+### Common Issues
+
+1. **Database errors**: Ensure the database file exists and has the correct permissions.
+   ```bash
+   # Check permissions
+   ls -l mcias.db
+   # Fix permissions if needed
+   chmod 644 mcias.db
+   ```
+
+2. **Port already in use**: If the port is already in use, specify a different port with the `-addr` flag.
+   ```bash
+   go run main.go -db ./mcias.db -addr :8081
+   ```
+
+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:
+
+```bash
+go run main.go -db ./mcias.db > mcias.log 2>&1
+```
+
+## 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