133 lines
No EOL
5 KiB
Markdown
133 lines
No EOL
5 KiB
Markdown
# ms-auth
|
|
|
|
`ms-auth` is a microservice designed for handling user authentication and authorization. It provides backend functionality for managing users, roles, permissions, and sessions using JWT. The service is developed in Go. PostgreSQL serves as the relational database for user data, and Valkey (or a compatible Redis instance) is used for session management.
|
|
|
|
For understanding the architecture, see the [documentation](https://git.sch9.ru/new_gate/docs).
|
|
|
|
### Prerequisites
|
|
|
|
Before you begin, ensure you have the following dependencies installed:
|
|
|
|
* **Docker** and **Docker Compose**: To run PostgreSQL and Valkey/Redis.
|
|
* **Goose**: For applying database migrations (`go install github.com/pressly/goose/v3/cmd/goose@latest`).
|
|
* **oapi-codegen**: For generating OpenAPI code (`go install github.com/deepmap/oapi-codegen/cmd/oapi-codegen@latest`).
|
|
|
|
### 1. Running Dependencies
|
|
|
|
You can run PostgreSQL and Valkey/Redis using Docker Compose. Create a `docker-compose.yml` file like the following:
|
|
|
|
```yaml
|
|
version: '3.8'
|
|
services:
|
|
valkey:
|
|
container_name: valkey
|
|
hostname: valkey
|
|
image: valkey/valkey:latest
|
|
volumes:
|
|
- ./conf/valkey.conf:/usr/local/etc/valkey/valkey.conf
|
|
- ./valkey-data:/data
|
|
command: [ "valkey-server", "/usr/local/etc/valkey/valkey.conf" ]
|
|
healthcheck:
|
|
test: [ "CMD-SHELL", "valkey-cli ping | grep PONG" ]
|
|
interval: 10s
|
|
timeout: 3s
|
|
retries: 5
|
|
ports:
|
|
- "6379:6379"
|
|
postgres:
|
|
image: postgres:14.1-alpine # Uses PostgreSQL 14.1 Alpine image
|
|
restart: always # Ensures the container restarts if it stops
|
|
environment:
|
|
POSTGRES_USER: postgres # Default user
|
|
POSTGRES_PASSWORD: supersecretpassword # Default password (change for production!)
|
|
POSTGRES_DB: postgres # Default database name
|
|
ports:
|
|
- '5432:5432' # Exposes PostgreSQL on the standard port 5432
|
|
volumes:
|
|
- ./postgres-data:/var/lib/postgresql/data # Persists database data locally
|
|
healthcheck:
|
|
test: pg_isready -U postgres -d postgres # Command to check if PostgreSQL is ready
|
|
interval: 10s # Check every 10 seconds
|
|
timeout: 3s # Wait 3 seconds for the check to respond
|
|
retries: 5 # Try 5 times before marking as unhealthy
|
|
volumes:
|
|
postgres-data: # Defines the named volume for data persistence
|
|
|
|
````
|
|
|
|
Start the services in detached mode:
|
|
|
|
```bash
|
|
docker-compose up -d
|
|
```
|
|
|
|
### 2. Configuration
|
|
|
|
The application uses environment variables for configuration. Create a `.env` file in the project root. The required variables are:
|
|
|
|
```dotenv
|
|
# Environment type (development or production)
|
|
ENV=dev # or prod
|
|
|
|
# Address and port where the ms-auth service will listen
|
|
ADDRESS=localhost:8090 # Default :8090
|
|
|
|
# PostgreSQL connection string (Data Source Name)
|
|
# Format: postgres://user:password@host:port/database?sslmode=disable
|
|
POSTGRES_DSN=postgres://postgres:supersecretpassword@localhost:5432/postgres?sslmode=disable
|
|
|
|
# Valkey/Redis connection string
|
|
# Format: valkey://<user>:<password>@<host>:<port>/<database>
|
|
REDIS_DSN=valkey://localhost:6379/0 # Adjust if using authentication or a different database
|
|
|
|
# Secret key for signing and verifying JWT tokens
|
|
JWT_SECRET=your_super_secret_jwt_key
|
|
|
|
# Optional: Initial admin credentials (defaults to admin/admin)
|
|
# ADMIN_USERNAME=admin
|
|
# ADMIN_PASSWORD=admin
|
|
```
|
|
|
|
**Important:** Replace `supersecretpassword` and `your_super_secret_jwt_key` with secure, unique values, especially for a production environment. Ensure the database credentials match your `docker-compose.yml` setup.
|
|
|
|
### 3. Database Migrations
|
|
|
|
The project uses `goose` to manage the database schema.
|
|
|
|
1. Ensure `goose` is installed:
|
|
```bash
|
|
go install github.com/pressly/goose/v3/cmd/goose@latest
|
|
```
|
|
2. Apply the migrations to the running PostgreSQL database. The migrations are located in the `./migrations` directory. Make sure the connection string in the command matches the `POSTGRES_DSN` from your `.env` file:
|
|
```bash
|
|
goose -dir ./migrations postgres "postgres://postgres:supersecretpassword@localhost:5432/postgres?sslmode=disable" up
|
|
```
|
|
|
|
### 4. OpenAPI Code Generation
|
|
|
|
The project uses OpenAPI to define its API. Go code for handlers and models is generated based on this specification using `oapi-codegen`. The configuration for generation is likely in `config.yaml` or a Makefile.
|
|
|
|
Assuming a Makefile exists similar to the `ms-tester` example:
|
|
|
|
```bash
|
|
make gen
|
|
```
|
|
|
|
Or, run `oapi-codegen` directly based on your project's specific OpenAPI definition file (e.g., `api/user/v1/user.yaml`) and the `config.yaml`:
|
|
|
|
```bash
|
|
# Example command (adjust paths/package names as needed):
|
|
oapi-codegen -config config.yaml api/user/v1/user.yaml
|
|
```
|
|
|
|
This generates the code specified in `config.yaml`, outputting to `./contracts/user/v1/user.go`.
|
|
|
|
### 5. Running the Application
|
|
|
|
Start the `ms-auth` service using the main package located in the `cmd/ms-auth` directory:
|
|
|
|
```bash
|
|
go run ./cmd/ms-auth/main.go
|
|
```
|
|
|
|
After starting, the service will be available at the address specified in the `ADDRESS` variable in your `.env` file (e.g., `http://localhost:8090`). |