Core implementation written with Junie.

docs/installation.org

@@ -0,0 +1,173 @@
+#+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