170 lines
3.0 KiB
Markdown
170 lines
3.0 KiB
Markdown
# 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 |