173 lines
3.3 KiB
Org Mode
173 lines
3.3 KiB
Org Mode
#+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 |