first commit
This commit is contained in:
SDI
+375
@@ -0,0 +1,375 @@
|
||||
---
|
||||
id: docker-hub-images
|
||||
title: Docker Hub Image Installation
|
||||
description: This document explains how to quickly install the system using the official ABC User Feedback images registered on Docker Hub.
|
||||
sidebar_position: 1
|
||||
---
|
||||
|
||||
# Docker Hub Image Installation
|
||||
|
||||
ABC User Feedback provides official Docker images.
|
||||
This document explains how to quickly set up the system locally using Docker Compose, including **Web UI, API server, database, SMTP server**, etc.
|
||||
|
||||
---
|
||||
|
||||
## 1. Prerequisites
|
||||
|
||||
| Item | Description |
|
||||
| -------------- | ------------------------------------------------------------------------ |
|
||||
| Docker | 20.10 or higher |
|
||||
| Docker Compose | v2 or higher recommended |
|
||||
| Ports Used | `3000`, `4000`, `13306`, `5080`, `25` (must be free on local machine) |
|
||||
|
||||
---
|
||||
|
||||
## 2. Docker Image Configuration
|
||||
|
||||
| Service Name | Description | Docker Image Name |
|
||||
| ----------------- | ----------------------------------------- | ------------------------------------ |
|
||||
| Web (Admin UI) | Frontend web UI (Next.js) | `line/abc-user-feedback-web` |
|
||||
| API (Backend) | Backend server (NestJS) | `line/abc-user-feedback-api` |
|
||||
| MySQL | Database | `mysql:8.0` |
|
||||
| SMTP4Dev | Email server for local testing | `rnwood/smtp4dev:v3` |
|
||||
| (Optional) OpenSearch | For search functionality and improved AI analysis accuracy | `opensearchproject/opensearch:2.16.0` |
|
||||
|
||||
---
|
||||
|
||||
## 3. `docker-compose.yml` Example
|
||||
|
||||
```yaml
|
||||
name: abc-user-feedback
|
||||
services:
|
||||
web:
|
||||
image: line/abc-user-feedback-web:latest
|
||||
environment:
|
||||
- NEXT_PUBLIC_API_BASE_URL=http://localhost:4000
|
||||
ports:
|
||||
- 3000:3000
|
||||
depends_on:
|
||||
- api
|
||||
restart: unless-stopped
|
||||
|
||||
api:
|
||||
image: line/abc-user-feedback-api:latest
|
||||
environment:
|
||||
- JWT_SECRET=jwtsecretjwtsecretjwtsecret
|
||||
- MYSQL_PRIMARY_URL=mysql://userfeedback:userfeedback@mysql:3306/userfeedback
|
||||
- SMTP_HOST=smtp4dev
|
||||
- SMTP_PORT=25
|
||||
- SMTP_SENDER=user@feedback.com
|
||||
# Uncomment below if using OpenSearch
|
||||
# - OPENSEARCH_USE=true
|
||||
# - OPENSEARCH_NODE=http://opensearch-node:9200
|
||||
ports:
|
||||
- 4000:4000
|
||||
depends_on:
|
||||
- mysql
|
||||
restart: unless-stopped
|
||||
|
||||
mysql:
|
||||
image: mysql:8.0
|
||||
command:
|
||||
[
|
||||
"--default-authentication-plugin=mysql_native_password",
|
||||
"--collation-server=utf8mb4_bin",
|
||||
]
|
||||
environment:
|
||||
MYSQL_ROOT_PASSWORD: userfeedback
|
||||
MYSQL_DATABASE: userfeedback
|
||||
MYSQL_USER: userfeedback
|
||||
MYSQL_PASSWORD: userfeedback
|
||||
TZ: UTC
|
||||
ports:
|
||||
- 13306:3306
|
||||
volumes:
|
||||
- mysql:/var/lib/mysql
|
||||
restart: unless-stopped
|
||||
|
||||
smtp4dev:
|
||||
image: rnwood/smtp4dev:v3
|
||||
ports:
|
||||
- 5080:80
|
||||
- 25:25
|
||||
- 143:143
|
||||
volumes:
|
||||
- smtp4dev:/smtp4dev
|
||||
restart: unless-stopped
|
||||
|
||||
# Uncomment below if you want to use OpenSearch
|
||||
# opensearch-node:
|
||||
# image: opensearchproject/opensearch:2.16.0
|
||||
# restart: unless-stopped
|
||||
# environment:
|
||||
# - cluster.name=opensearch-cluster
|
||||
# - node.name=opensearch-node
|
||||
# - discovery.type=single-node
|
||||
# - bootstrap.memory_lock=true
|
||||
# - 'OPENSEARCH_JAVA_OPTS=-Xms512m -Xmx512m'
|
||||
# - plugins.security.disabled=true
|
||||
# - OPENSEARCH_INITIAL_ADMIN_PASSWORD=UserFeedback123!@#
|
||||
# ulimits:
|
||||
# memlock:
|
||||
# soft: -1
|
||||
# hard: -1
|
||||
# nofile:
|
||||
# soft: 65536
|
||||
# hard: 65536
|
||||
# volumes:
|
||||
# - opensearch:/usr/share/opensearch/data
|
||||
# ports:
|
||||
# - 9200:9200
|
||||
# - 9600:9600
|
||||
|
||||
volumes:
|
||||
mysql:
|
||||
smtp4dev:
|
||||
# opensearch:
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 4. Execution Steps
|
||||
|
||||
### 4.1 Download and Run Docker Images
|
||||
|
||||
```bash
|
||||
# Run all services in the background using Docker Compose
|
||||
docker compose up -d
|
||||
```
|
||||
|
||||
### 4.2 Check Running Status
|
||||
|
||||
```bash
|
||||
# Check if all containers are running normally
|
||||
docker compose ps
|
||||
```
|
||||
|
||||
### 4.3 Check Service Access
|
||||
|
||||
- **Web Application**: [http://localhost:3000](http://localhost:3000)
|
||||
- **API Server**: [http://localhost:4000](http://localhost:4000)
|
||||
- **SMTP Test Page**: [http://localhost:5080](http://localhost:5080)
|
||||
- **MySQL Database**: `localhost:13306` (user: `userfeedback`, password: `userfeedback`)
|
||||
|
||||
---
|
||||
|
||||
## 5. SMTP Configuration
|
||||
|
||||
By default, this configuration allows you to test emails through `smtp4dev`.
|
||||
|
||||
- **Web Interface**: [http://localhost:5080](http://localhost:5080)
|
||||
- **SMTP Port**: `25`
|
||||
- **IMAP Port**: `143`
|
||||
|
||||
### SMTP Testing Method
|
||||
|
||||
1. Register a user or use the user invitation feature in the web application
|
||||
2. Check sent emails at [http://localhost:5080](http://localhost:5080)
|
||||
3. Test email content and attachments
|
||||
|
||||
> **Important**: In actual production environments, you must integrate with an external SMTP server (e.g., Gmail, SendGrid, corporate SMTP, etc.).
|
||||
|
||||
## 6. Installation Verification
|
||||
|
||||
### 6.1 Web Application Access Verification
|
||||
|
||||
Access `http://localhost:3000` in your browser and verify:
|
||||
|
||||
- Tenant creation screen displays normally
|
||||
- Page loading completes
|
||||
- No JavaScript errors (check in browser developer tools)
|
||||
|
||||
### 6.2 API Server Status Check
|
||||
|
||||
```bash
|
||||
# API server health check
|
||||
curl http://localhost:4000/api/health
|
||||
```
|
||||
|
||||
Expected response:
|
||||
|
||||
```json
|
||||
{
|
||||
"status": "ok",
|
||||
"info": {
|
||||
"database": {
|
||||
"status": "up"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 6.3 Database Connection Verification
|
||||
|
||||
```bash
|
||||
# Directly access MySQL container to check database
|
||||
docker compose exec mysql mysql -u userfeedback -puserfeedback -e "SHOW DATABASES;"
|
||||
|
||||
# Check table creation
|
||||
docker compose exec mysql mysql -u userfeedback -puserfeedback -e "USE userfeedback; SHOW TABLES;"
|
||||
```
|
||||
|
||||
### 6.4 Log Check
|
||||
|
||||
```bash
|
||||
# Check logs for all services
|
||||
docker compose logs
|
||||
|
||||
# Check logs for specific service only
|
||||
docker compose logs api
|
||||
docker compose logs web
|
||||
docker compose logs mysql
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 7. OpenSearch Usage Notes
|
||||
|
||||
OpenSearch is an optional component that improves search functionality and AI analysis accuracy.
|
||||
|
||||
### 7.1 How to Enable OpenSearch
|
||||
|
||||
1. Uncomment environment variables in the `api` service in `docker-compose.yml`:
|
||||
|
||||
```yaml
|
||||
- OPENSEARCH_USE=true
|
||||
- OPENSEARCH_NODE=http://opensearch-node:9200
|
||||
```
|
||||
|
||||
2. Uncomment the `opensearch-node` service
|
||||
3. Uncomment `opensearch:` in the `volumes:` section
|
||||
4. Ensure ports `9200`, `9600` are not in use on local machine
|
||||
|
||||
### 7.2 Memory Requirements
|
||||
|
||||
> **Warning**: OpenSearch requires at least 2GB of memory. If memory is insufficient, the container may automatically terminate.
|
||||
|
||||
### 7.3 OpenSearch Status Check
|
||||
|
||||
```bash
|
||||
# Check OpenSearch cluster status
|
||||
curl http://localhost:9200/_cluster/health
|
||||
|
||||
# Check OpenSearch node information
|
||||
curl http://localhost:9200/_nodes
|
||||
|
||||
# Check indices
|
||||
curl http://localhost:9200/_cat/indices
|
||||
```
|
||||
|
||||
### 7.4 Disabling OpenSearch
|
||||
|
||||
To not use OpenSearch, comment out the corresponding service and environment variables in `docker-compose.yml`.
|
||||
|
||||
---
|
||||
|
||||
## 8. Troubleshooting
|
||||
|
||||
### 8.1 Port Conflict Issue
|
||||
|
||||
**Symptom**: Port binding error occurs when running `docker compose up`
|
||||
|
||||
**Solution**:
|
||||
|
||||
```bash
|
||||
# Check ports in use
|
||||
lsof -i :3000 # Web port
|
||||
lsof -i :4000 # API port
|
||||
lsof -i :13306 # MySQL port
|
||||
lsof -i :5080 # SMTP port
|
||||
|
||||
# Stop processes using those ports and restart
|
||||
docker compose down
|
||||
docker compose up -d
|
||||
```
|
||||
|
||||
### 8.2 Container Startup Failure
|
||||
|
||||
**Symptom**: Some containers fail to start or keep restarting
|
||||
|
||||
**Solution**:
|
||||
|
||||
```bash
|
||||
# Check container status
|
||||
docker compose ps
|
||||
|
||||
# Check logs for failed container
|
||||
docker compose logs [service-name]
|
||||
|
||||
# Stop and remove all containers
|
||||
docker compose down
|
||||
|
||||
# Remove volumes as well (warning: data loss)
|
||||
docker compose down -v
|
||||
|
||||
# Start again
|
||||
docker compose up -d
|
||||
```
|
||||
|
||||
### 8.3 Database Connection Error
|
||||
|
||||
**Symptom**: MySQL connection failure from API server
|
||||
|
||||
**Solution**:
|
||||
|
||||
```bash
|
||||
# Wait until MySQL container is fully started
|
||||
docker compose logs mysql
|
||||
|
||||
# Test direct connection to MySQL container
|
||||
docker compose exec mysql mysql -u userfeedback -puserfeedback -e "SELECT 1;"
|
||||
|
||||
# Restart API service
|
||||
docker compose restart api
|
||||
```
|
||||
|
||||
### 8.4 Image Download Failure
|
||||
|
||||
**Symptom**: Cannot download Docker images
|
||||
|
||||
**Solution**:
|
||||
|
||||
```bash
|
||||
# Check Docker Hub login
|
||||
docker login
|
||||
|
||||
# Manually download images
|
||||
docker pull line/abc-user-feedback-web:latest
|
||||
docker pull line/abc-user-feedback-api:latest
|
||||
|
||||
# Check network connection
|
||||
ping hub.docker.com
|
||||
```
|
||||
|
||||
### 8.5 Memory Insufficient Issue
|
||||
|
||||
**Symptom**: OpenSearch container automatically terminates
|
||||
|
||||
**Solution**:
|
||||
|
||||
```bash
|
||||
# Check system memory
|
||||
free -h
|
||||
|
||||
# Check Docker memory usage
|
||||
docker stats
|
||||
|
||||
# Disable OpenSearch (comment out in docker-compose.yml)
|
||||
# Or increase memory allocation
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 9. Reference Links
|
||||
|
||||
- [ABC User Feedback Web - Docker Hub](https://hub.docker.com/r/line/abc-user-feedback-web)
|
||||
- [ABC User Feedback API - Docker Hub](https://hub.docker.com/r/line/abc-user-feedback-api)
|
||||
- [smtp4dev - Docker Hub](https://hub.docker.com/r/rnwood/smtp4dev)
|
||||
- [OpenSearch - Docker Hub](https://hub.docker.com/r/opensearchproject/opensearch)
|
||||
|
||||
---
|
||||
|
||||
## Related Documents
|
||||
|
||||
- [Initial Setup Guide](/en/user-guide/getting-started)
|
||||
|
||||
+273
@@ -0,0 +1,273 @@
|
||||
---
|
||||
sidebar_position: 2
|
||||
title: "CLI Tool Usage"
|
||||
description: "This document explains how to quickly and easily install and manage the system using the ABC User Feedback CLI tool."
|
||||
---
|
||||
|
||||
# CLI Tool Usage
|
||||
|
||||
The ABC User Feedback CLI (`auf-cli`) is a command-line tool that simplifies system installation, execution, and management. As long as Node.js and Docker are installed, you can run it immediately via `npx` without installing additional dependencies or cloning the repository.
|
||||
|
||||
## Main Features
|
||||
|
||||
- Automatic setup of required infrastructure (MySQL, SMTP, OpenSearch)
|
||||
- Simplified environment variable configuration
|
||||
- Automatic start/stop of API and web servers
|
||||
- Volume data cleanup
|
||||
- Dynamic Docker Compose file generation
|
||||
|
||||
## Docker Images Used
|
||||
|
||||
- `line/abc-user-feedback-web:latest` - Web frontend
|
||||
- `line/abc-user-feedback-api:latest` - API backend
|
||||
- `mysql:8.0` - Database
|
||||
- `rnwood/smtp4dev:v3` - SMTP test server
|
||||
- `opensearchproject/opensearch:2.16.0` - Search engine (optional)
|
||||
|
||||
## Prerequisites
|
||||
|
||||
Before using the CLI tool, you must meet the following requirements:
|
||||
|
||||
- [Node.js v22 or higher](https://nodejs.org/en/download/)
|
||||
- [Docker](https://docs.docker.com/desktop/)
|
||||
|
||||
## Basic Commands
|
||||
|
||||
### Initialization
|
||||
|
||||
To set up the infrastructure required for ABC User Feedback, run the following command:
|
||||
|
||||
```bash
|
||||
npx auf-cli init
|
||||
```
|
||||
|
||||
This command performs the following tasks:
|
||||
|
||||
1. Creates `config.toml` file for environment variable configuration
|
||||
2. Sets up required infrastructure according to architecture (ARM/AMD)
|
||||
|
||||
After initialization is complete, a `config.toml` file is created in the current directory. You can edit this file as needed to adjust environment variables.
|
||||
|
||||
### Starting Server
|
||||
|
||||
To start the API and web servers, run the following command:
|
||||
|
||||
```bash
|
||||
npx auf-cli start
|
||||
```
|
||||
|
||||
This command performs the following tasks:
|
||||
|
||||
1. Reads environment variables from `config.toml` file
|
||||
2. Generates Docker Compose file and starts services
|
||||
3. Starts API and web server containers and required infrastructure (MySQL, SMTP, OpenSearch)
|
||||
|
||||
After the server starts successfully, you can access the ABC User Feedback web interface at `http://localhost:3000` (or configured URL) in your web browser. The CLI displays the following URLs:
|
||||
|
||||
- Web interface URL
|
||||
- API URL
|
||||
- MySQL connection string
|
||||
- OpenSearch URL (if enabled)
|
||||
- SMTP web interface (when using smtp4dev)
|
||||
|
||||
### Stopping Server
|
||||
|
||||
To stop the API and web servers, run the following command:
|
||||
|
||||
```bash
|
||||
npx auf-cli stop
|
||||
```
|
||||
|
||||
This command stops running API and web server containers and infrastructure containers. All data stored in volumes is preserved.
|
||||
|
||||
### Volume Cleanup
|
||||
|
||||
To clean up Docker volumes created during startup, run the following command:
|
||||
|
||||
```bash
|
||||
npx auf-cli clean
|
||||
```
|
||||
|
||||
This command stops all containers and deletes Docker volumes for MySQL, SMTP, OpenSearch, etc.
|
||||
|
||||
**Warning**: This operation deletes all data, so back up if needed.
|
||||
|
||||
You can also clean up unused Docker images using the `--images` option:
|
||||
|
||||
```bash
|
||||
npx auf-cli clean --images
|
||||
```
|
||||
|
||||
## Configuration File (config.toml)
|
||||
|
||||
Running the `init` command creates a `config.toml` file in the current directory. This file is used to configure environment variables for ABC User Feedback.
|
||||
|
||||
The following is an example of a `config.toml` file:
|
||||
|
||||
```toml
|
||||
[web]
|
||||
port = 3000
|
||||
# api_base_url = "http://localhost:4000"
|
||||
|
||||
[api]
|
||||
port = 4000
|
||||
jwt_secret = "jwtsecretjwtsecretjwtsecretjwtsecretjwtsecretjwtsecret"
|
||||
|
||||
# master_api_key = "MASTER_KEY"
|
||||
# access_token_expired_time = "10m"
|
||||
# refresh_token_expired_time = "1h"
|
||||
|
||||
# [api.auto_feedback_deletion]
|
||||
# enabled = true
|
||||
# period_days = 365
|
||||
|
||||
# [api.smtp]
|
||||
# host = "smtp4dev" # SMTP_HOST
|
||||
# port = 25 # SMTP_PORT
|
||||
# sender = "user@feedback.com"
|
||||
# username=
|
||||
# password=
|
||||
# tls=
|
||||
# cipher_spec=
|
||||
# opportunitic_tls=
|
||||
|
||||
# [api.opensearch]
|
||||
# enabled = true
|
||||
|
||||
[mysql]
|
||||
port = 13306
|
||||
```
|
||||
|
||||
You can edit this file as needed to adjust environment variables. For detailed information on environment variables, refer to the [Environment Variable Settings](./05-configuration.md) document.
|
||||
|
||||
## Advanced Usage
|
||||
|
||||
### Changing Ports
|
||||
|
||||
By default, the web server uses port 3000 and the API server uses port 4000. To change these, modify the following settings in the `config.toml` file:
|
||||
|
||||
```toml
|
||||
[web]
|
||||
port = 8000 # Change web server port
|
||||
api_base_url = "http://localhost:8080" # API URL must also be changed
|
||||
|
||||
[api]
|
||||
port = 8080 # Change API server port
|
||||
|
||||
[mysql]
|
||||
port = 13307 # Change MySQL port if needed
|
||||
```
|
||||
|
||||
### Enabling OpenSearch
|
||||
|
||||
To enable OpenSearch for advanced search features:
|
||||
|
||||
```toml
|
||||
[api.opensearch]
|
||||
enabled = true
|
||||
```
|
||||
|
||||
**Notes**:
|
||||
|
||||
- OpenSearch requires at least 2GB of available memory
|
||||
- OpenSearch container is available at `http://localhost:9200`
|
||||
- Check OpenSearch status: `http://localhost:9200/_cluster/health`
|
||||
|
||||
### SMTP Settings
|
||||
|
||||
For development environments, the default `smtp4dev` settings are recommended:
|
||||
|
||||
```toml
|
||||
[api.smtp]
|
||||
host = "smtp4dev"
|
||||
port = 25
|
||||
sender = "dev@feedback.local"
|
||||
```
|
||||
|
||||
The smtp4dev web interface is available at `http://localhost:5080` to check sent emails.
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Common Issues
|
||||
|
||||
1. **Docker-related errors**:
|
||||
|
||||
- Check if Docker is running: `docker --version`
|
||||
- Check Docker permissions: `docker ps`
|
||||
- Verify Docker Desktop is properly installed and running
|
||||
|
||||
2. **Port conflicts**:
|
||||
|
||||
- Check port usage: `lsof -i :PORT` (macOS/Linux) or `netstat -ano | findstr :PORT` (Windows)
|
||||
- Change port settings in `config.toml`
|
||||
- Common conflicting ports: 3000, 4000, 13306, 9200, 5080
|
||||
|
||||
3. **Service startup failure**:
|
||||
|
||||
- Check container logs: `docker compose logs SERVICE_NAME`
|
||||
- Verify Docker images are available: `docker images`
|
||||
- Check sufficient system resources (memory, disk space)
|
||||
|
||||
4. **Database connection issues**:
|
||||
- Check MySQL container status: `docker compose ps mysql`
|
||||
- Check MySQL logs: `docker compose logs mysql`
|
||||
- Test connection: `docker compose exec mysql mysql -u userfeedback -p`
|
||||
|
||||
### Debugging Tips
|
||||
|
||||
1. **Check container logs**:
|
||||
|
||||
```bash
|
||||
# All container logs
|
||||
docker compose logs
|
||||
|
||||
# Specific service logs
|
||||
docker compose logs api
|
||||
docker compose logs web
|
||||
docker compose logs mysql
|
||||
```
|
||||
|
||||
2. **Check service status**:
|
||||
|
||||
```bash
|
||||
# Check API status
|
||||
curl http://localhost:4000/api/health
|
||||
|
||||
# Check OpenSearch status (if enabled)
|
||||
curl http://localhost:9200/_cluster/health
|
||||
```
|
||||
|
||||
3. **Direct database access**:
|
||||
```bash
|
||||
# Connect to MySQL
|
||||
docker compose exec mysql mysql -u userfeedback -p userfeedback
|
||||
```
|
||||
|
||||
## Limitations
|
||||
|
||||
The CLI tool is designed for development and testing environments. For production deployment, consider the following:
|
||||
|
||||
1. **Security Considerations**:
|
||||
|
||||
- Use environment variables instead of configuration files for sensitive data
|
||||
- Implement proper secret management
|
||||
- Use production-grade JWT secrets
|
||||
- Enable HTTPS/TLS encryption
|
||||
|
||||
2. **Scalability and Availability**:
|
||||
|
||||
- Use orchestration tools like Kubernetes or Docker Swarm
|
||||
- Implement load balancing and auto-scaling
|
||||
- Set up proper monitoring and alerts
|
||||
- Use managed database services (RDS, Cloud SQL, etc.)
|
||||
|
||||
3. **Data Management**:
|
||||
- Implement automated backup strategies
|
||||
- Use persistent volumes with proper backups
|
||||
- Consider data retention policies
|
||||
- Monitor disk usage and performance
|
||||
|
||||
## Next Steps
|
||||
|
||||
For detailed API and web server configuration options, refer to the [Environment Variable Settings](./05-configuration.md) document.
|
||||
|
||||
+276
@@ -0,0 +1,276 @@
|
||||
---
|
||||
sidebar_position: 3
|
||||
title: 'Manual Installation'
|
||||
description: 'Manual installation guide for building and running ABC User Feedback directly from source code'
|
||||
---
|
||||
|
||||
# Manual Installation
|
||||
|
||||
This document explains how to manually install and configure ABC User Feedback. This is useful when you want to build and run the application directly from source code.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
Before proceeding with manual installation, you must meet the following requirements:
|
||||
|
||||
- [Node.js v22.19.0 or higher](https://nodejs.org/en/download/)
|
||||
- [pnpm v10.15.0 or higher](https://pnpm.io/installation) (package manager)
|
||||
- [Git](https://git-scm.com/downloads)
|
||||
- [MySQL 8.0](https://www.mysql.com/downloads/)
|
||||
- SMTP server
|
||||
- (Optional) [OpenSearch 2.16](https://opensearch.org/)
|
||||
|
||||
## Downloading Source Code
|
||||
|
||||
First, clone the ABC User Feedback source code from the GitHub repository:
|
||||
|
||||
```bash
|
||||
git clone https://github.com/line/abc-user-feedback.git
|
||||
cd abc-user-feedback
|
||||
```
|
||||
|
||||
## Infrastructure Setup
|
||||
|
||||
ABC User Feedback requires a MySQL database, SMTP server, and optionally OpenSearch. There are several ways to set up these infrastructure components.
|
||||
|
||||
### Infrastructure Setup Using Docker
|
||||
|
||||
The simplest method is to set up required infrastructure with Docker Compose:
|
||||
|
||||
```bash
|
||||
docker-compose -f docker/docker-compose.infra.yml up -d
|
||||
```
|
||||
|
||||
### Using Existing Infrastructure
|
||||
|
||||
If you already have MySQL, OpenSearch, or SMTP server, you can configure connection information as environment variables later.
|
||||
|
||||
## Installing Dependencies
|
||||
|
||||
ABC User Feedback uses a monorepo structure managed through TurboRepo. To install dependencies for all packages:
|
||||
|
||||
```bash
|
||||
pnpm install
|
||||
```
|
||||
|
||||
After installing dependencies, build all packages:
|
||||
|
||||
```bash
|
||||
pnpm build
|
||||
```
|
||||
|
||||
## Environment Variable Configuration
|
||||
|
||||
### API Server Environment Variables
|
||||
|
||||
Create a `.env` file in the `apps/api` directory and configure it by referring to `.env.example`:
|
||||
|
||||
```env
|
||||
# Required environment variables
|
||||
JWT_SECRET=DEV
|
||||
|
||||
MYSQL_PRIMARY_URL=mysql://userfeedback:userfeedback@localhost:13306/userfeedback # required
|
||||
|
||||
ACCESS_TOKEN_EXPIRED_TIME=10m # default: 10m
|
||||
REFRESH_TOKEN_EXPIRED_TIME=1h # default: 1h
|
||||
|
||||
# Optional environment variables
|
||||
|
||||
# APP_PORT=4000 # default: 4000
|
||||
# APP_ADDRESS=0.0.0.0 # default: 0.0.0.0
|
||||
|
||||
# MYSQL_SECONDARY_URLS= ["mysql://userfeedback:userfeedback@localhost:13306/userfeedback"] # optional
|
||||
|
||||
SMTP_HOST=localhost # required
|
||||
SMTP_PORT=25 # required
|
||||
SMTP_SENDER=user@feedback.com # required
|
||||
# SMTP_USERNAME= # optional
|
||||
# SMTP_PASSWORD= # optional
|
||||
# SMTP_TLS= # default: false
|
||||
# SMTP_CIPHER_SPEC= # default: TLSv1.2 if SMTP_TLS=true
|
||||
# SMTP_OPPORTUNISTIC_TLS= # default: true if SMTP_TLS=true
|
||||
|
||||
# OPENSEARCH_USE=false # default: false
|
||||
# OPENSEARCH_NODE= # required if OPENSEARCH_USE=true
|
||||
# OPENSEARCH_USERNAME= # optional
|
||||
# OPENSEARCH_PASSWORD= # optional
|
||||
|
||||
# AUTO_MIGRATION=true # default: true
|
||||
|
||||
# MASTER_API_KEY= # default: none
|
||||
|
||||
# BASE_URL=https://api.example.com # Public API server URL used in Swagger documentation (optional)
|
||||
|
||||
# AUTO_FEEDBACK_DELETION_ENABLED=false # default: false
|
||||
# AUTO_FEEDBACK_DELETION_PERIOD_DAYS=365*5
|
||||
```
|
||||
|
||||
### Web Server Environment Variables
|
||||
|
||||
Create a `.env` file in the `apps/web` directory and configure it by referring to `.env.example`:
|
||||
|
||||
```env
|
||||
NEXT_PUBLIC_API_BASE_URL=http://localhost:4000
|
||||
```
|
||||
|
||||
For detailed information on environment variables, refer to the [Environment Variable Settings](./05-configuration.md) document.
|
||||
|
||||
## Database Migration
|
||||
|
||||
Before running the API server for the first time, you need to create the database schema. If you set the `AUTO_MIGRATION=true` environment variable, migrations will run automatically when the server starts.
|
||||
|
||||
To run migrations manually:
|
||||
|
||||
```bash
|
||||
cd apps/api
|
||||
npm run migration:run
|
||||
```
|
||||
|
||||
## Running in Development Mode
|
||||
|
||||
### Running with Single Command
|
||||
|
||||
To run the API server and web server in development mode:
|
||||
|
||||
```bash
|
||||
# From project root directory
|
||||
pnpm dev
|
||||
```
|
||||
|
||||
This command starts both the API server and web server simultaneously. The API server runs on port 4000 by default, and the web server runs on port 3000.
|
||||
|
||||
### Running Individual Packages
|
||||
|
||||
#### Building Common Packages
|
||||
|
||||
Before running the web application, you need to build shared packages:
|
||||
|
||||
```bash
|
||||
# From project root directory
|
||||
cd packages/ufb-shared
|
||||
pnpm build
|
||||
```
|
||||
|
||||
#### Building UI Packages
|
||||
|
||||
Before running the web application, you need to build UI packages:
|
||||
|
||||
```bash
|
||||
# From project root directory
|
||||
cd packages/ufb-tailwindcss
|
||||
pnpm build
|
||||
```
|
||||
|
||||
#### Running Each Server Individually
|
||||
|
||||
To run each server individually:
|
||||
|
||||
```bash
|
||||
# Run API server only
|
||||
cd apps/api
|
||||
pnpm dev
|
||||
|
||||
# Run web server only
|
||||
cd apps/web
|
||||
pnpm dev
|
||||
```
|
||||
|
||||
## Production Build
|
||||
|
||||
To build the application for production environment:
|
||||
|
||||
```bash
|
||||
# From project root directory
|
||||
pnpm build
|
||||
```
|
||||
|
||||
This command builds both the API server and web server.
|
||||
|
||||
## Running in Production Mode
|
||||
|
||||
To run the production build:
|
||||
|
||||
```bash
|
||||
# Run API server
|
||||
cd apps/api
|
||||
pnpm start
|
||||
|
||||
# Run web server
|
||||
cd apps/web
|
||||
pnpm start
|
||||
```
|
||||
|
||||
## API Type Generation
|
||||
|
||||
When the backend API is running, you can generate API types for the frontend:
|
||||
|
||||
```bash
|
||||
cd apps/web
|
||||
pnpm generate-api-type
|
||||
```
|
||||
|
||||
This command generates TypeScript types from OpenAPI specification and saves them to the `src/shared/types/api.type.ts` file.
|
||||
|
||||
**Note**: For this command to work properly, the API server must be running at `http://localhost:4000`.
|
||||
|
||||
## Code Quality Management
|
||||
|
||||
### Linting
|
||||
|
||||
To run code linting:
|
||||
|
||||
```bash
|
||||
pnpm lint
|
||||
```
|
||||
|
||||
### Formatting
|
||||
|
||||
To run code formatting:
|
||||
|
||||
```bash
|
||||
pnpm format
|
||||
```
|
||||
|
||||
### Testing
|
||||
|
||||
To run tests:
|
||||
|
||||
```bash
|
||||
pnpm test
|
||||
```
|
||||
|
||||
## Swagger Documentation
|
||||
|
||||
When the API server is running, you can check Swagger documentation at the following endpoints:
|
||||
|
||||
- **API Documentation**: http://localhost:4000/docs
|
||||
- **Admin API Documentation**: http://localhost:4000/admin-docs
|
||||
- **OpenAPI JSON**: http://localhost:4000/docs-json
|
||||
- **Admin OpenAPI JSON**: http://localhost:4000/admin-docs-json
|
||||
|
||||
> **Note**: If you are serving the API server on a different URL (e.g., behind a reverse proxy), you can set the `BASE_URL` environment variable to generate correct API endpoint URLs in the Swagger documentation. Example: `BASE_URL=https://api.example.com`
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Common Issues
|
||||
|
||||
1. **Dependency Installation Errors**:
|
||||
- Verify Node.js version is v22.19.0 or higher.
|
||||
- Verify pnpm version is v10.15.0 or higher.
|
||||
- Update pnpm to the latest version.
|
||||
- Try `pnpm install --force`.
|
||||
|
||||
2. **Database Connection Errors**:
|
||||
- Verify MySQL server is running.
|
||||
- Verify database credentials are correct.
|
||||
- Verify `MYSQL_PRIMARY_URL` environment variable format is correct.
|
||||
- If using Docker infrastructure, verify MySQL is running on port 13306 (not 3306).
|
||||
|
||||
3. **Build Errors**:
|
||||
- Verify UI packages are built (`pnpm build:ui`).
|
||||
- Verify all dependencies are installed.
|
||||
- Check TypeScript errors.
|
||||
|
||||
4. **Runtime Errors**:
|
||||
- Verify environment variables are set correctly.
|
||||
- Verify required ports are available.
|
||||
- Check error messages in logs.
|
||||
+165
@@ -0,0 +1,165 @@
|
||||
---
|
||||
id: smtp-configuration
|
||||
title: SMTP Server Integration Guide
|
||||
description: This guide explains how to integrate with external SMTP servers for sending authentication emails in production environments.
|
||||
sidebar_position: 4
|
||||
---
|
||||
|
||||
# SMTP Server Integration Guide
|
||||
|
||||
In production environments, instead of local test servers like `smtp4dev`,
|
||||
you need to connect to **external SMTP servers (Gmail, SendGrid, company SMTP, etc.)**
|
||||
to properly send authentication emails (registration, password reset, etc.).
|
||||
|
||||
This document explains environment variable configuration for SMTP server integration and major integration examples.
|
||||
|
||||
---
|
||||
|
||||
## 1. SMTP-Related Environment Variables
|
||||
|
||||
Set the following environment variables in the `api` service or `.env` file:
|
||||
|
||||
> **Note**: For SMTP servers that do not require authentication, `SMTP_USERNAME` and `SMTP_PASSWORD` can be omitted.
|
||||
|
||||
| Environment Variable | Description | Required |
|
||||
| ---------------------------------- | ------------------------------------------------------ | -------- |
|
||||
| `SMTP_HOST` | SMTP server address (e.g., smtp.gmail.com) | Required |
|
||||
| `SMTP_PORT` | Port number (usually 587, 465, etc.) | Required |
|
||||
| `SMTP_SENDER` | Sender email address (e.g., `noreply@yourdomain.com`) | Required |
|
||||
| `SMTP_USERNAME` | SMTP authentication username (account ID) | Optional |
|
||||
| `SMTP_PASSWORD` | SMTP authentication password or API key | Optional |
|
||||
| `SMTP_TLS` | Whether to use TLS (`true` or `false`) | Optional |
|
||||
| `SMTP_CIPHER_SPEC` | TLS encryption algorithm (default: `TLSv1.2`) | Optional |
|
||||
| `SMTP_OPPORTUNISTIC_TLS` | Whether to use STARTTLS (`true` or `false`) | Optional |
|
||||
|
||||
> **Important**: In actual code, `SMTP_USERNAME` and `SMTP_PASSWORD` are used, and `SMTP_TLS=true` is mainly used for port 465, while `false` is mainly used for port 587.
|
||||
|
||||
---
|
||||
|
||||
## 2. Docker Environment Example
|
||||
|
||||
```yaml
|
||||
api:
|
||||
image: line/abc-user-feedback-api
|
||||
environment:
|
||||
- SMTP_HOST=smtp.gmail.com
|
||||
- SMTP_PORT=587
|
||||
- SMTP_USERNAME=your-email@gmail.com
|
||||
- SMTP_PASSWORD=your-email-app-password
|
||||
- SMTP_SENDER=noreply@yourdomain.com
|
||||
- SMTP_TLS=false
|
||||
- SMTP_OPPORTUNISTIC_TLS=true
|
||||
```
|
||||
|
||||
Or you can manage it separately with a `.env` file:
|
||||
|
||||
```env
|
||||
SMTP_HOST=smtp.gmail.com
|
||||
SMTP_PORT=587
|
||||
SMTP_USERNAME=your-email@gmail.com
|
||||
SMTP_PASSWORD=your-email-app-password
|
||||
SMTP_SENDER=noreply@yourdomain.com
|
||||
SMTP_TLS=false
|
||||
SMTP_OPPORTUNISTIC_TLS=true
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 3. SMTP Integration Examples
|
||||
|
||||
### ✅ Gmail SMTP Integration (for personal testing)
|
||||
|
||||
- `SMTP_HOST`: `smtp.gmail.com`
|
||||
- `SMTP_PORT`: `587`
|
||||
- `SMTP_USERNAME`: Gmail address (e.g., `abc@gmail.com`)
|
||||
- `SMTP_PASSWORD`: **App password** (Allow less secure apps → not recommended)
|
||||
- `SMTP_TLS`: `false`
|
||||
- `SMTP_OPPORTUNISTIC_TLS`: `true`
|
||||
|
||||
> If **two-factor authentication** is enabled on your Gmail account, you must create an [app password](https://myaccount.google.com/apppasswords).
|
||||
|
||||
---
|
||||
|
||||
### ✅ SendGrid Integration (Recommended)
|
||||
|
||||
- `SMTP_HOST`: `smtp.sendgrid.net`
|
||||
- `SMTP_PORT`: `587`
|
||||
- `SMTP_USERNAME`: `apikey`
|
||||
- `SMTP_PASSWORD`: Actual SendGrid API Key
|
||||
- `SMTP_SENDER`: verified sender address
|
||||
- `SMTP_TLS`: `false`
|
||||
- `SMTP_OPPORTUNISTIC_TLS`: `true`
|
||||
|
||||
---
|
||||
|
||||
## 4. Testing Methods
|
||||
|
||||
### 4.1 Email Sending Test
|
||||
|
||||
1. **Email Verification Test**:
|
||||
|
||||
- Create admin or user account
|
||||
- Verify email verification code is sent
|
||||
|
||||
2. **Password Reset Test**:
|
||||
|
||||
- Request password reset
|
||||
- Verify email with reset link is received
|
||||
|
||||
3. **User Invitation Test**:
|
||||
- Admin invites new user
|
||||
- Verify invitation email is sent
|
||||
|
||||
### 4.2 Log Checking
|
||||
|
||||
If email sending fails, check detailed logs with the following command:
|
||||
|
||||
```bash
|
||||
# Docker Compose environment
|
||||
docker compose logs api
|
||||
|
||||
# Check logs for specific time period
|
||||
docker compose logs --since=10m api
|
||||
|
||||
# Real-time log monitoring
|
||||
docker compose logs -f api
|
||||
```
|
||||
|
||||
If SMTP errors occur, detailed messages will be displayed in the logs.
|
||||
|
||||
---
|
||||
|
||||
## 5. Troubleshooting
|
||||
|
||||
| Problem Type | Cause or Solution |
|
||||
| ----------------------------- | -------------------------------------- |
|
||||
| Authentication Error (`535`) | Recheck `SMTP_USERNAME` / `SMTP_PASSWORD` |
|
||||
| Connection Refused (`ECONNREFUSED`) | Firewall or incorrect port settings |
|
||||
| Email Not Arriving | `SMTP_SENDER` is not verified |
|
||||
| TLS Error (`ETLS`) | `SMTP_TLS` setting is incorrect |
|
||||
| STARTTLS Failure | Check `SMTP_OPPORTUNISTIC_TLS` setting |
|
||||
|
||||
---
|
||||
|
||||
## 6. Email Templates Related to SMTP
|
||||
|
||||
Currently, emails are sent in the following situations:
|
||||
|
||||
- **Email Verification**: Send verification code when admin/user registers
|
||||
- **Password Reset**: Send link when password reset is requested
|
||||
- **User Invitation**: Send invitation email when admin invites user
|
||||
|
||||
Email content is based on **Handlebars templates** and includes the following information:
|
||||
|
||||
- Sender: `"User feedback" <SMTP_SENDER>`
|
||||
- Base URL: Uses `ADMIN_WEB_URL` environment variable value
|
||||
- Template location: `src/configs/modules/mailer-config/templates/`
|
||||
|
||||
---
|
||||
|
||||
## Related Documents
|
||||
|
||||
- [Docker Hub Installation Guide](./docker-hub-images)
|
||||
- [Environment Variable Settings](./configuration)
|
||||
- [Getting Started Guide](/en/user-guide/getting-started)
|
||||
|
||||
+207
@@ -0,0 +1,207 @@
|
||||
---
|
||||
id: configuration
|
||||
title: Environment Variable Configuration
|
||||
description: This document explains how to configure environment variables for ABC User Feedback's API and web servers.
|
||||
sidebar_position: 5
|
||||
---
|
||||
|
||||
# Environment Variable Configuration
|
||||
|
||||
This document explains the main environment variables used by ABC User Feedback's **API server** and **web server** and how to configure them.
|
||||
|
||||
---
|
||||
|
||||
## 1. API Server Environment Variables
|
||||
|
||||
### Required Environment Variables
|
||||
|
||||
| Environment Variable | Description | Default | Example |
|
||||
| ---------------------------- | ----------------------------- | ------- | -------------------------------- |
|
||||
| `JWT_SECRET` | Secret key for JWT signing | None | `jwtsecretjwtsecretjwtsecret` |
|
||||
| `MYSQL_PRIMARY_URL` | MySQL connection URL | None | `mysql://user:pass@host:3306/db` |
|
||||
| `ACCESS_TOKEN_EXPIRED_TIME` | Access Token validity period | `10m` | `10m`, `30s`, `1h` |
|
||||
| `REFRESH_TOKEN_EXPIRED_TIME` | Refresh Token validity period | `1h` | `1h`, `7d` |
|
||||
|
||||
> JWT secret should be a sufficiently complex and secure string.
|
||||
|
||||
⚠️ **Security Notes**:
|
||||
|
||||
- `JWT_SECRET` should be at least 32 characters long and complex
|
||||
- Never use default values in production environments
|
||||
- Do not include environment variable files (`.env`) in version control
|
||||
- Manage sensitive information through environment variables or secret management systems
|
||||
|
||||
---
|
||||
|
||||
### Optional Environment Variables
|
||||
|
||||
| Environment Variable | Description | Default | Example |
|
||||
| ---------------------- | --------------------------------------------------- | ----------------------- | --------------------------- |
|
||||
| `APP_PORT` | API server port | `4000` | `4000` |
|
||||
| `APP_ADDRESS` | Binding address | `0.0.0.0` | `127.0.0.1` |
|
||||
| `ADMIN_WEB_URL` | Admin web URL | `http://localhost:3000` | `https://admin.company.com` |
|
||||
| `BASE_URL` | Public API server URL used in Swagger documentation | None | `https://api.example.com` |
|
||||
| `MYSQL_SECONDARY_URLS` | Secondary DB URLs (JSON array) | None | `["mysql://..."]` |
|
||||
| `AUTO_MIGRATION` | Auto migration on app startup | `true` | `false` |
|
||||
| `MASTER_API_KEY` | Master permission API key (optional) | None | `abc123xyz` |
|
||||
| `NODE_OPTIONS` | Node execution options | None | `--max_old_space_size=4096` |
|
||||
|
||||
---
|
||||
|
||||
### SMTP Settings (Email Authentication)
|
||||
|
||||
| Environment Variable | Description | Example |
|
||||
| ------------------------ | ---------------------------- | ------------------------------ |
|
||||
| `SMTP_HOST` | SMTP server address | `smtp.gmail.com` |
|
||||
| `SMTP_PORT` | Port (usually 587 or 465) | `587` |
|
||||
| `SMTP_USERNAME` | Login username | `user@example.com` |
|
||||
| `SMTP_PASSWORD` | Login password or token | `app-password` |
|
||||
| `SMTP_SENDER` | Sender address | `noreply@company.com` |
|
||||
| `SMTP_BASE_URL` | Base URL for links in emails | `https://feedback.company.com` |
|
||||
| `SMTP_TLS` | Whether to use TLS | `true` |
|
||||
| `SMTP_CIPHER_SPEC` | Encryption spec | `TLSv1.2` |
|
||||
| `SMTP_OPPORTUNISTIC_TLS` | Whether to support STARTTLS | `true` |
|
||||
|
||||
📎 For detailed settings, refer to the [SMTP Integration Guide](./04-smtp-configuration.md).
|
||||
|
||||
---
|
||||
|
||||
## 2. OpenSearch Settings (Optional)
|
||||
|
||||
| Environment Variable | Description | Example |
|
||||
| --------------------- | ---------------------------- | ----------------------- |
|
||||
| `OPENSEARCH_USE` | Whether to enable OpenSearch | `true` |
|
||||
| `OPENSEARCH_NODE` | OpenSearch node URL | `http://localhost:9200` |
|
||||
| `OPENSEARCH_USERNAME` | Authentication ID | `admin` |
|
||||
| `OPENSEARCH_PASSWORD` | Authentication password | `admin123` |
|
||||
|
||||
> OpenSearch is used to improve search speed and AI features.
|
||||
|
||||
---
|
||||
|
||||
## 3. Automatic Feedback Deletion Settings
|
||||
|
||||
| Environment Variable | Description | Default / Condition |
|
||||
| ------------------------------------ | ------------------------------------ | --------------------------- |
|
||||
| `AUTO_FEEDBACK_DELETION_ENABLED` | Enable old feedback deletion feature | `false` |
|
||||
| `AUTO_FEEDBACK_DELETION_PERIOD_DAYS` | Deletion criteria in days | `365` (required if enabled) |
|
||||
|
||||
---
|
||||
|
||||
## 4. API Log Export Settings (Optional)
|
||||
|
||||
The API can export application logs through OpenTelemetry in addition to the standard console logs.
|
||||
|
||||
<!-- markdownlint-disable MD060 -->
|
||||
|
||||
| Environment Variable | Description | Default | Example |
|
||||
| ---------------------------------- | ---------------------------------------------------------------- | ------- | ---------------------------------------------------------- |
|
||||
| `OTEL_EXPORTER_OTLP_LOGS_ENDPOINT` | OTLP HTTP logs endpoint used by the pino OpenTelemetry transport | None | `http://localhost:4319/v1/logs` |
|
||||
| `OTEL_RESOURCE_ATTRIBUTES` | OpenTelemetry resource attributes for exported logs | None | `service.name=abc-user-feedback-api,service.version=1.1.1` |
|
||||
|
||||
<!-- markdownlint-enable MD060 -->
|
||||
|
||||
> When `OTEL_EXPORTER_OTLP_LOGS_ENDPOINT` is set, the API keeps writing pretty console logs and also sends the same logs to the configured OTLP HTTP endpoint.
|
||||
> If you also set `OTEL_RESOURCE_ATTRIBUTES`, you can attach standard OpenTelemetry resource metadata such as `service.name` and `service.version` using comma-separated `key=value` pairs.
|
||||
> Use the example values from `apps/api/.env.example` as the baseline when configuring local development environments.
|
||||
|
||||
### Local Verification Flow
|
||||
|
||||
- Start the local OTEL test stack from the repository root:
|
||||
|
||||
```bash
|
||||
docker compose -f docker/docker-compose.otel-test.yml up -d
|
||||
```
|
||||
|
||||
- Set the following variables in `apps/api/.env` based on the example in `apps/api/.env.example`:
|
||||
|
||||
```env
|
||||
OTEL_EXPORTER_OTLP_LOGS_ENDPOINT=http://localhost:4319/v1/logs
|
||||
OTEL_RESOURCE_ATTRIBUTES=service.name=abc-user-feedback-api,service.version=1.1.1
|
||||
```
|
||||
|
||||
> The API does not parse this value itself. `pino-opentelemetry-transport` and the OpenTelemetry SDK consume these standard OTEL environment variables directly.
|
||||
|
||||
- Start the API server and trigger requests that generate logs.
|
||||
- Vector should receive OTLP logs on port `4319` and print transformed log records to its console output.
|
||||
- OpenSearch should be reachable on host port `9201`.
|
||||
- OpenSearch Dashboards should be reachable on [http://localhost:5602](http://localhost:5602), where you can inspect the `logs-*` indices created by the local stack.
|
||||
|
||||
> The local test stack uses OTLP HTTP on `4319`, OpenSearch on `9201`, and OpenSearch Dashboards on `5602` as defined in `docker/docker-compose.otel-test.yml`.
|
||||
|
||||
---
|
||||
|
||||
## 5. Web Server Environment Variables
|
||||
|
||||
### Required Environment Variables
|
||||
|
||||
| Environment Variable | Description | Example |
|
||||
| -------------------------- | --------------------------------- | ----------------------- |
|
||||
| `NEXT_PUBLIC_API_BASE_URL` | API server address for client use | `http://localhost:4000` |
|
||||
|
||||
### Optional Environment Variables
|
||||
|
||||
| Environment Variable | Description | Default | Example |
|
||||
| -------------------- | ------------- | ------- | ------- |
|
||||
| `PORT` | Frontend port | `3000` | `3000` |
|
||||
|
||||
---
|
||||
|
||||
## 6. Configuration Methods
|
||||
|
||||
### Docker Compose Example
|
||||
|
||||
```yaml
|
||||
services:
|
||||
api:
|
||||
image: line/abc-user-feedback-api
|
||||
environment:
|
||||
- JWT_SECRET=changeme
|
||||
- MYSQL_PRIMARY_URL=mysql://user:pass@mysql:3306/userfeedback
|
||||
- SMTP_HOST=smtp.sendgrid.net
|
||||
- SMTP_USERNAME=apikey
|
||||
- SMTP_PASSWORD=your-sendgrid-key
|
||||
```
|
||||
|
||||
### .env File Example
|
||||
|
||||
```env
|
||||
# apps/api/.env
|
||||
JWT_SECRET=changemechangemechangeme
|
||||
MYSQL_PRIMARY_URL=mysql://root:pass@localhost:3306/db
|
||||
ACCESS_TOKEN_EXPIRED_TIME=10m
|
||||
REFRESH_TOKEN_EXPIRED_TIME=1h
|
||||
SMTP_HOST=smtp.example.com
|
||||
SMTP_SENDER=noreply@example.com
|
||||
# BASE_URL=https://api.example.com # Set when serving behind a reverse proxy
|
||||
|
||||
# apps/web/.env
|
||||
NEXT_PUBLIC_API_BASE_URL=http://localhost:4000
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 7. Troubleshooting Guide
|
||||
|
||||
<!-- markdownlint-disable MD060 -->
|
||||
|
||||
| Problem | Cause and Solution |
|
||||
| --------------------------------------- | ----------------------------------------------------------------------------------------------------------------------- |
|
||||
| Environment variables not recognized | Check `.env` location or restart container |
|
||||
| DB connection failure | Check `MYSQL_PRIMARY_URL` format or connection info |
|
||||
| SMTP error | Recheck port/TLS settings or authentication info |
|
||||
| OpenSearch error | Check node URL or user authentication |
|
||||
| OTEL log export not working | Check whether `OTEL_EXPORTER_OTLP_LOGS_ENDPOINT` is set, verify the endpoint URL, and confirm the OTEL stack is running |
|
||||
| JWT token error | Check `JWT_SECRET` length and complexity |
|
||||
| Environment variable validation failure | Check for missing required variables or type errors |
|
||||
| Port conflict | Check `APP_PORT`, `PORT` settings |
|
||||
|
||||
<!-- markdownlint-enable MD060 -->
|
||||
|
||||
---
|
||||
|
||||
## Related Documents
|
||||
|
||||
- [Docker Installation Guide](./docker-hub-images)
|
||||
- [SMTP Integration Guide](./smtp-configuration)
|
||||
- [Getting Started Guide](/en/user-guide/getting-started)
|
||||
+5
@@ -0,0 +1,5 @@
|
||||
{
|
||||
"position": 1,
|
||||
"label": "Installation",
|
||||
"description": "Guide for setting up development environment and installation."
|
||||
}
|
||||
+7
@@ -0,0 +1,7 @@
|
||||
---
|
||||
title: Installation
|
||||
---
|
||||
|
||||
import DocCardList from '@theme/DocCardList';
|
||||
|
||||
<DocCardList />
|
||||
+533
@@ -0,0 +1,533 @@
|
||||
---
|
||||
sidebar_position: 2
|
||||
title: "API Integration"
|
||||
description: "This guide explains how to integrate external systems using ABC User Feedback API and provides actual implementation examples."
|
||||
---
|
||||
|
||||
# API Integration
|
||||
|
||||
ABC User Feedback can integrate with external systems through **RESTful API**. You can programmatically collect feedback, manage issues, and query data, making it easy to integrate with existing services or workflows.
|
||||
|
||||
---
|
||||
|
||||
## API Basic Information
|
||||
|
||||
### Official API Documentation
|
||||
|
||||
The **complete API documentation** for ABC User Feedback can be found at the following link:
|
||||
|
||||
🔗 **[Official API Documentation (Redocly)](https://line.github.io/abc-user-feedback/)**
|
||||
|
||||
This documentation provides detailed specs for all endpoints, request/response examples, and an interface for actual testing.
|
||||
|
||||
### Base URL
|
||||
|
||||
```
|
||||
https://your-domain.com/api
|
||||
```
|
||||
|
||||
### Authentication Method
|
||||
|
||||
All API requests use **API key-based authentication**.
|
||||
|
||||
```http
|
||||
X-API-KEY: your-api-key-here
|
||||
Content-Type: application/json
|
||||
```
|
||||
|
||||
:::warning Security Notice
|
||||
Use API keys only on the server side, and do not expose them to clients (browsers, mobile apps).
|
||||
:::
|
||||
|
||||
### API Key Issuance Method
|
||||
|
||||
1. **Access Admin Page**: Log in to ABC User Feedback admin page
|
||||
2. **Project Settings**: Navigate to the settings page for the project
|
||||
3. **API Key Management**: Create a new API key from the "API Key Management" menu
|
||||
4. **Copy Key**: Save the generated API key in a safe place
|
||||
|
||||
:::info API Key Permissions
|
||||
API keys are issued per project and can only access data for that project.
|
||||
:::
|
||||
|
||||
---
|
||||
|
||||
## Main API Endpoint Examples
|
||||
|
||||
### 1. Creating Feedback
|
||||
|
||||
#### Basic Feedback Creation
|
||||
|
||||
```javascript
|
||||
const createFeedback = async (
|
||||
projectId,
|
||||
channelId,
|
||||
message,
|
||||
issueNames = []
|
||||
) => {
|
||||
const response = await fetch(
|
||||
`/api/projects/${projectId}/channels/${channelId}/feedbacks`,
|
||||
{
|
||||
method: "POST",
|
||||
headers: {
|
||||
"Content-Type": "application/json",
|
||||
"X-API-KEY": "your-api-key-here",
|
||||
},
|
||||
body: JSON.stringify({
|
||||
message: message,
|
||||
issueNames: issueNames,
|
||||
}),
|
||||
}
|
||||
);
|
||||
|
||||
return await response.json();
|
||||
};
|
||||
|
||||
// Usage example
|
||||
const feedback = await createFeedback(1, 1, "Payment error occurred", [
|
||||
"Payment",
|
||||
"Error",
|
||||
]);
|
||||
```
|
||||
|
||||
### 2. Querying Feedback
|
||||
|
||||
#### Channel-Based Feedback Search
|
||||
|
||||
```javascript
|
||||
const searchFeedbacks = async (
|
||||
projectId,
|
||||
channelId,
|
||||
searchText,
|
||||
limit = 10,
|
||||
page = 1
|
||||
) => {
|
||||
const response = await fetch(
|
||||
`/api/projects/${projectId}/channels/${channelId}/feedbacks/search`,
|
||||
{
|
||||
method: "POST",
|
||||
headers: {
|
||||
"Content-Type": "application/json",
|
||||
"X-API-KEY": "your-api-key-here",
|
||||
},
|
||||
body: JSON.stringify({
|
||||
limit: limit,
|
||||
page: page,
|
||||
query: {
|
||||
searchText: searchText,
|
||||
createdAt: {
|
||||
gte: "2024-01-01",
|
||||
lt: "2024-12-31",
|
||||
},
|
||||
},
|
||||
sort: {
|
||||
createdAt: "DESC",
|
||||
},
|
||||
}),
|
||||
}
|
||||
);
|
||||
|
||||
return await response.json();
|
||||
};
|
||||
|
||||
// Usage example
|
||||
const feedbacks = await searchFeedbacks(1, 1, "Payment", 20, 1);
|
||||
console.log(
|
||||
`Retrieved ${feedbacks.items.length} out of ${feedbacks.meta.totalItems} feedback`
|
||||
);
|
||||
```
|
||||
|
||||
#### Single Feedback Query
|
||||
|
||||
```javascript
|
||||
const getFeedbackById = async (projectId, channelId, feedbackId) => {
|
||||
const response = await fetch(
|
||||
`/api/projects/${projectId}/channels/${channelId}/feedbacks/${feedbackId}`,
|
||||
{
|
||||
method: "GET",
|
||||
headers: {
|
||||
"X-API-KEY": "your-api-key-here",
|
||||
},
|
||||
}
|
||||
);
|
||||
|
||||
return await response.json();
|
||||
};
|
||||
|
||||
// Usage example
|
||||
const feedback = await getFeedbackById(1, 1, 123);
|
||||
console.log("Feedback details:", feedback);
|
||||
```
|
||||
|
||||
#### Feedback Update
|
||||
|
||||
```javascript
|
||||
const updateFeedback = async (projectId, channelId, feedbackId, updateData) => {
|
||||
const response = await fetch(
|
||||
`/api/projects/${projectId}/channels/${channelId}/feedbacks/${feedbackId}`,
|
||||
{
|
||||
method: "PUT",
|
||||
headers: {
|
||||
"Content-Type": "application/json",
|
||||
"X-API-KEY": "your-api-key-here",
|
||||
},
|
||||
body: JSON.stringify(updateData),
|
||||
}
|
||||
);
|
||||
|
||||
return await response.json();
|
||||
};
|
||||
|
||||
// Usage example
|
||||
const updatedFeedback = await updateFeedback(1, 1, 123, {
|
||||
message: "Updated feedback content",
|
||||
issueNames: ["Updated issue"],
|
||||
});
|
||||
```
|
||||
|
||||
#### Feedback Deletion
|
||||
|
||||
```javascript
|
||||
const deleteFeedbacks = async (projectId, channelId, feedbackIds) => {
|
||||
const response = await fetch(
|
||||
`/api/projects/${projectId}/channels/${channelId}/feedbacks`,
|
||||
{
|
||||
method: "DELETE",
|
||||
headers: {
|
||||
"Content-Type": "application/json",
|
||||
"X-API-KEY": "your-api-key-here",
|
||||
},
|
||||
body: JSON.stringify({
|
||||
feedbackIds: feedbackIds,
|
||||
}),
|
||||
}
|
||||
);
|
||||
|
||||
return await response.json();
|
||||
};
|
||||
|
||||
// Usage example
|
||||
const result = await deleteFeedbacks(1, 1, [123, 124, 125]);
|
||||
console.log("Deletion complete:", result);
|
||||
```
|
||||
|
||||
### 3. Issue Management
|
||||
|
||||
#### Issue Creation
|
||||
|
||||
```javascript
|
||||
const createIssue = async (projectId, name, description) => {
|
||||
const response = await fetch(`/api/projects/${projectId}/issues`, {
|
||||
method: "POST",
|
||||
headers: {
|
||||
"Content-Type": "application/json",
|
||||
"X-API-KEY": "your-api-key-here",
|
||||
},
|
||||
body: JSON.stringify({
|
||||
name: name,
|
||||
description: description,
|
||||
}),
|
||||
});
|
||||
|
||||
return await response.json();
|
||||
};
|
||||
|
||||
// Usage example
|
||||
const issue = await createIssue(
|
||||
1,
|
||||
"Payment Error",
|
||||
"User experienced error during payment process"
|
||||
);
|
||||
```
|
||||
|
||||
#### Issue Search
|
||||
|
||||
```javascript
|
||||
const searchIssues = async (projectId, query = {}) => {
|
||||
const response = await fetch(`/api/projects/${projectId}/issues/search`, {
|
||||
method: "POST",
|
||||
headers: {
|
||||
"Content-Type": "application/json",
|
||||
"X-API-KEY": "your-api-key-here",
|
||||
},
|
||||
body: JSON.stringify({
|
||||
limit: 10,
|
||||
page: 1,
|
||||
query: query,
|
||||
sort: {
|
||||
createdAt: "DESC",
|
||||
},
|
||||
}),
|
||||
});
|
||||
|
||||
return await response.json();
|
||||
};
|
||||
|
||||
// Usage example
|
||||
const issues = await searchIssues(1, { name: "Payment" });
|
||||
```
|
||||
|
||||
#### Issue Query
|
||||
|
||||
```javascript
|
||||
const getIssueById = async (projectId, issueId) => {
|
||||
const response = await fetch(`/api/projects/${projectId}/issues/${issueId}`, {
|
||||
method: "GET",
|
||||
headers: {
|
||||
"X-API-KEY": "your-api-key-here",
|
||||
},
|
||||
});
|
||||
|
||||
return await response.json();
|
||||
};
|
||||
|
||||
// Usage example
|
||||
const issue = await getIssueById(1, 123);
|
||||
console.log("Issue details:", issue);
|
||||
```
|
||||
|
||||
#### Issue Update
|
||||
|
||||
```javascript
|
||||
const updateIssue = async (projectId, issueId, updateData) => {
|
||||
const response = await fetch(`/api/projects/${projectId}/issues/${issueId}`, {
|
||||
method: "PUT",
|
||||
headers: {
|
||||
"Content-Type": "application/json",
|
||||
"X-API-KEY": "your-api-key-here",
|
||||
},
|
||||
body: JSON.stringify(updateData),
|
||||
});
|
||||
|
||||
return await response.json();
|
||||
};
|
||||
|
||||
// Usage example
|
||||
const updatedIssue = await updateIssue(1, 123, {
|
||||
name: "Updated issue name",
|
||||
description: "Updated issue description",
|
||||
});
|
||||
```
|
||||
|
||||
#### Issue Deletion
|
||||
|
||||
```javascript
|
||||
const deleteIssues = async (projectId, issueIds) => {
|
||||
const response = await fetch(`/api/projects/${projectId}/issues`, {
|
||||
method: "DELETE",
|
||||
headers: {
|
||||
"Content-Type": "application/json",
|
||||
"X-API-KEY": "your-api-key-here",
|
||||
},
|
||||
body: JSON.stringify({
|
||||
issueIds: issueIds,
|
||||
}),
|
||||
});
|
||||
|
||||
return await response.json();
|
||||
};
|
||||
|
||||
// Usage example
|
||||
const result = await deleteIssues(1, [123, 124, 125]);
|
||||
console.log("Issue deletion complete:", result);
|
||||
```
|
||||
|
||||
#### Adding Issue to Feedback
|
||||
|
||||
```javascript
|
||||
const addIssueToFeedback = async (
|
||||
projectId,
|
||||
channelId,
|
||||
feedbackId,
|
||||
issueId
|
||||
) => {
|
||||
const response = await fetch(
|
||||
`/api/projects/${projectId}/channels/${channelId}/feedbacks/${feedbackId}/issues/${issueId}`,
|
||||
{
|
||||
method: "POST",
|
||||
headers: {
|
||||
"X-API-KEY": "your-api-key-here",
|
||||
},
|
||||
}
|
||||
);
|
||||
|
||||
return await response.json();
|
||||
};
|
||||
|
||||
// Usage example
|
||||
const result = await addIssueToFeedback(1, 1, 123, 456);
|
||||
console.log("Issue added:", result);
|
||||
```
|
||||
|
||||
#### Removing Issue from Feedback
|
||||
|
||||
```javascript
|
||||
const removeIssueFromFeedback = async (
|
||||
projectId,
|
||||
channelId,
|
||||
feedbackId,
|
||||
issueId
|
||||
) => {
|
||||
const response = await fetch(
|
||||
`/api/projects/${projectId}/channels/${channelId}/feedbacks/${feedbackId}/issues/${issueId}`,
|
||||
{
|
||||
method: "DELETE",
|
||||
headers: {
|
||||
"X-API-KEY": "your-api-key-here",
|
||||
},
|
||||
}
|
||||
);
|
||||
|
||||
return await response.json();
|
||||
};
|
||||
|
||||
// Usage example
|
||||
const result = await removeIssueFromFeedback(1, 1, 123, 456);
|
||||
console.log("Issue removed:", result);
|
||||
```
|
||||
|
||||
### 4. Project and Channel Information
|
||||
|
||||
#### Project Information Query
|
||||
|
||||
```javascript
|
||||
const getProjectInfo = async (projectId) => {
|
||||
const response = await fetch(`/api/projects/${projectId}`, {
|
||||
method: "GET",
|
||||
headers: {
|
||||
"X-API-KEY": "your-api-key-here",
|
||||
},
|
||||
});
|
||||
|
||||
return await response.json();
|
||||
};
|
||||
|
||||
// Usage example
|
||||
const project = await getProjectInfo(1);
|
||||
console.log("Project information:", project);
|
||||
```
|
||||
|
||||
#### Channel Field Query
|
||||
|
||||
```javascript
|
||||
const getChannelFields = async (projectId, channelId) => {
|
||||
const response = await fetch(
|
||||
`/api/projects/${projectId}/channels/${channelId}/fields`,
|
||||
{
|
||||
method: "GET",
|
||||
headers: {
|
||||
"X-API-KEY": "your-api-key-here",
|
||||
},
|
||||
}
|
||||
);
|
||||
|
||||
return await response.json();
|
||||
};
|
||||
|
||||
// Usage example
|
||||
const fields = await getChannelFields(1, 1);
|
||||
console.log("Channel fields:", fields);
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## API Testing via Swagger
|
||||
|
||||
ABC User Feedback provides **Swagger UI** to easily test and understand the API.
|
||||
|
||||
### Swagger Access Method
|
||||
|
||||
Access via **API server address + `/docs`**:
|
||||
|
||||
```
|
||||
https://your-domain.com/api/docs
|
||||
```
|
||||
|
||||
Or in **ReDoc format**:
|
||||
|
||||
```
|
||||
https://your-domain.com/api/docs/redoc
|
||||
```
|
||||
|
||||
### Setting API Key in Swagger
|
||||
|
||||
1. Click the **"Authorize"** button at the top of Swagger UI
|
||||
2. Enter the issued API key in the **X-API-KEY** field
|
||||
3. Click **"Authorize"** to complete authentication
|
||||
|
||||
After this, all API requests will automatically include the API key for testing.
|
||||
|
||||
### Swagger Usage Tips
|
||||
|
||||
- Use **"Try it out"** button to test actual API calls
|
||||
- Check actual response data structure in **Response body** section
|
||||
- View detailed request/response data format in **Schema** tab
|
||||
- Generate **cURL** commands automatically for CLI testing
|
||||
|
||||
---
|
||||
|
||||
## Error Handling and Retry Logic
|
||||
|
||||
### HTTP Status Codes
|
||||
|
||||
| Status Code | Meaning | Handling Method |
|
||||
| ----------- | ---------------- | ----------------------------- |
|
||||
| **200** | Success | Normal processing |
|
||||
| **400** | Bad Request | Validate request data |
|
||||
| **401** | Authentication Failed | Check API key |
|
||||
| **403** | Forbidden | Check project access permissions |
|
||||
| **404** | Not Found | Check ID value |
|
||||
| **429** | Rate Limit Exceeded | Retry after a moment |
|
||||
| **500** | Server Error | Retry or contact support team |
|
||||
|
||||
## Response Data Parsing Method
|
||||
|
||||
### Pagination Response Structure
|
||||
|
||||
```json
|
||||
{
|
||||
"meta": {
|
||||
"itemCount": 10,
|
||||
"totalItems": 100,
|
||||
"itemsPerPage": 10,
|
||||
"totalPages": 10,
|
||||
"currentPage": 1
|
||||
},
|
||||
"items": [
|
||||
{
|
||||
"id": 1,
|
||||
"message": "Feedback content",
|
||||
"createdAt": "2024-01-01T00:00:00.000Z",
|
||||
"issues": [
|
||||
{
|
||||
"id": 1,
|
||||
"name": "Issue name"
|
||||
}
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
## Security and Performance Optimization
|
||||
|
||||
### API Key Security
|
||||
|
||||
- **Use environment variables**: Manage API keys as environment variables
|
||||
- **Server side only**: Do not expose API keys to clients
|
||||
- **Key rotation**: Regularly replace API keys
|
||||
- **IP whitelist**: Allow access only from specific IPs when possible
|
||||
|
||||
### Performance Optimization
|
||||
|
||||
- **Use pagination**: Set appropriate limit when querying large amounts of data
|
||||
- **Request only needed fields**: Improve response speed through query optimization
|
||||
- **Caching strategy**: Cache frequently queried data on client side
|
||||
- **Batch processing**: Process multiple requests together
|
||||
|
||||
## Related Documents
|
||||
|
||||
- [API Key Management](/en/user-guide/settings/api-key-management) - How to issue API keys from UI
|
||||
- [Image Settings](/en/user-guide/settings/image-setting) - Settings for using image upload API
|
||||
- [Webhook Integration](/en/user-guide/settings/webhook-management) - Real-time notification settings that can be used with API
|
||||
|
||||
+172
@@ -0,0 +1,172 @@
|
||||
---
|
||||
sidebar_position: 3
|
||||
title: "OAuth Integration"
|
||||
description: "This guide explains how to integrate single sign-on (SSO) through Google OAuth and custom OAuth providers."
|
||||
---
|
||||
|
||||
# OAuth Integration
|
||||
|
||||
By setting up OAuth 2.0-based single sign-on (SSO) in ABC User Feedback, users can log in with existing accounts (Google, Microsoft, GitHub, etc.) without creating separate accounts. This improves user convenience and is essential for implementing integrated authentication in enterprise environments.
|
||||
|
||||
---
|
||||
|
||||
## OAuth Integration Overview
|
||||
|
||||
OAuth methods supported by ABC User Feedback:
|
||||
|
||||
### 1. Google OAuth
|
||||
|
||||
- Provided by default without additional setup
|
||||
- Easy login via Google account
|
||||
|
||||
### 2. Custom OAuth Provider
|
||||
|
||||
- In-house authentication systems
|
||||
- Other OAuth 2.0/OpenID Connect compatible services
|
||||
|
||||
After setting up OAuth, it can be used alongside existing email login, and you can restrict to OAuth only according to organizational policy.
|
||||
|
||||
---
|
||||
|
||||
## Google OAuth Integration Settings
|
||||
|
||||
### Settings in Google Cloud Console
|
||||
|
||||
#### 1. Access Google Cloud Console
|
||||
|
||||
Access [Google Cloud Console](https://console.cloud.google.com) and create a project or select an existing project.
|
||||
|
||||
#### 2. Create OAuth 2.0 Client ID
|
||||
|
||||
1. Navigate to **APIs & Services > Credentials** menu
|
||||
2. Select **+ Create Credentials > OAuth Client ID**
|
||||
3. Select application type as **Web Application**
|
||||
|
||||
#### 3. Set Authorized Redirect URIs
|
||||
|
||||
Add the following URL to **Authorized Redirect URIs**:
|
||||
|
||||
```
|
||||
https://your-domain.com/auth/oauth-callback
|
||||
```
|
||||
|
||||
Examples:
|
||||
|
||||
- `https://feedback.company.com/auth/oauth-callback`
|
||||
- `http://localhost:3000/auth/oauth-callback` (development environment)
|
||||
|
||||
#### 4. Check Client Information
|
||||
|
||||
After creation is complete, check and copy the following information:
|
||||
|
||||
- **Client ID**: `1234567890-abc123def456.apps.googleusercontent.com`
|
||||
- **Client Secret**: `GOCSPX-abcdef123456`
|
||||
|
||||
### Google OAuth Settings in ABC User Feedback
|
||||
|
||||
To use Google OAuth, follow these steps to configure:
|
||||
|
||||
#### 1. Enable Google OAuth Settings
|
||||
|
||||
In **Settings > Login Management**:
|
||||
|
||||
1. Enable **OAuth2.0 Login** toggle
|
||||
2. Select **Login Button Type** as "Google Login"
|
||||
3. Enter information obtained from Google Cloud Console:
|
||||
- **Client ID**: Client ID created in Google Cloud Console
|
||||
- **Client Secret**: Client secret created in Google Cloud Console
|
||||
- **Authorization Code Request URL**: `https://accounts.google.com/o/oauth2/v2/auth`
|
||||
- **Scope**: `openid email profile`
|
||||
- **Access Token URL**: `https://oauth2.googleapis.com/token`
|
||||
- **User Profile Request URL**: `https://www.googleapis.com/oauth2/v2/userinfo`
|
||||
- **Email Key**: `email`
|
||||
|
||||
#### 2. Register Redirect URI
|
||||
|
||||
Add the following URL to **Authorized Redirect URIs** in Google Cloud Console:
|
||||
|
||||
```
|
||||
https://your-domain.com/auth/oauth-callback
|
||||
```
|
||||
|
||||
For development environment:
|
||||
|
||||
```
|
||||
http://localhost:3000/auth/oauth-callback
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Custom OAuth Provider Integration
|
||||
|
||||
### In-House Authentication System Integration
|
||||
|
||||
ABC User Feedback can integrate with in-house authentication systems used in enterprise environments. Most in-house authentication systems support OAuth 2.0 or OpenID Connect standards, so integration is possible through standard OAuth flow.
|
||||
|
||||
#### Requirements for In-House Authentication System Settings
|
||||
|
||||
To integrate with an in-house authentication system, the following information is required:
|
||||
|
||||
1. **OAuth Client Registration**
|
||||
|
||||
- Client ID
|
||||
- Client Secret
|
||||
- Redirect URI: `https://your-domain.com/auth/oauth-callback`
|
||||
|
||||
2. **OAuth Endpoint Information**
|
||||
|
||||
- Authorization URL (authentication request URL)
|
||||
- Token URL (token exchange URL)
|
||||
- User Info URL (user information query URL)
|
||||
|
||||
3. **Permission Scope (Scope)**
|
||||
- User profile information access permissions
|
||||
- Email address access permissions
|
||||
|
||||
#### Common In-House Authentication System Examples
|
||||
|
||||
| Item | Description | In-House System Example |
|
||||
| ---------------------------------- | ----------------------------------------- | ------------------------------------------------- |
|
||||
| **Login Button Type** | Login button type | `CUSTOM` |
|
||||
| **Login Button Name** | Name displayed on login button | `Sign in with Company Account` |
|
||||
| **Client ID** | OAuth client ID | `company-auth-client-123` |
|
||||
| **Client Secret** | Client secret | `company-secret-abc123` |
|
||||
| **Authorization Code Request URL** | User authentication request URL | `https://auth.company.com/oauth/authorize` |
|
||||
| **Scope** | Permission scope to request | `openid email profile` |
|
||||
| **Access Token URL** | Token request URL | `https://auth.company.com/oauth/token` |
|
||||
| **User Profile Request URL** | User information query API | `https://auth.company.com/api/user` |
|
||||
| **Email Key** | Email field name in user information JSON | `email` or `mail` |
|
||||
|
||||
### Other OAuth 2.0/OpenID Connect Compatible Services
|
||||
|
||||
ABC User Feedback can integrate with all authentication services that comply with OAuth 2.0 or OpenID Connect standards.
|
||||
|
||||
#### Supported Service Types
|
||||
|
||||
- **OpenID Connect Providers**: Services supporting standard OpenID Connect protocol
|
||||
- **OAuth 2.0 Providers**: Services supporting OAuth 2.0 Authorization Code flow
|
||||
- **Custom Authentication Servers**: Self-built services providing standard OAuth endpoints
|
||||
|
||||
#### Integration Setup Method
|
||||
|
||||
Configure custom OAuth in **Settings > Login Management**:
|
||||
|
||||
1. **Log in with admin account** and navigate to **Settings > Login Management** menu
|
||||
2. Enable **OAuth2.0 Login** toggle
|
||||
3. Select **Login Button Type** as `CUSTOM`
|
||||
4. Enter information received from authentication service provider:
|
||||
- **Login Button Name**: Text displayed on login button (e.g., "Sign in with Company Account")
|
||||
- **Client ID**: OAuth client identifier
|
||||
- **Client Secret**: Client authentication secret
|
||||
- **Authorization Code Request URL**: User authentication request URL
|
||||
- **Scope**: Permission scope to request (space-separated, e.g., "openid email profile")
|
||||
- **Access Token URL**: Access token request URL
|
||||
- **User Profile Request URL**: User profile information query URL
|
||||
- **Email Key**: Email field name in user information JSON (e.g., "email" or "mail")
|
||||
|
||||
---
|
||||
|
||||
## Related Documents
|
||||
|
||||
- [Login Management](/en/user-guide/settings/tenant-settings) - How to configure OAuth in UI
|
||||
|
||||
+303
@@ -0,0 +1,303 @@
|
||||
---
|
||||
sidebar_position: 4
|
||||
title: 'Webhook Integration'
|
||||
description: 'This guide explains how to integrate with external systems in real-time using webhooks and provides implementation examples.'
|
||||
---
|
||||
|
||||
# Webhook Integration
|
||||
|
||||
With webhooks, you can deliver major events occurring in ABC User Feedback to external systems in real-time. You can integrate with Slack notifications, automation workflows, custom analysis systems, etc.
|
||||
|
||||
---
|
||||
|
||||
## Supported Event Types
|
||||
|
||||
Events supported by ABC User Feedback are as follows:
|
||||
|
||||
### 1. FEEDBACK_CREATION
|
||||
|
||||
Occurs when new feedback is created.
|
||||
|
||||
**Request Headers:**
|
||||
|
||||
```
|
||||
Content-Type: application/json
|
||||
x-webhook-token: your-secret-token
|
||||
```
|
||||
|
||||
**Payload Example:**
|
||||
|
||||
```json
|
||||
{
|
||||
"event": "FEEDBACK_CREATION",
|
||||
"data": {
|
||||
"feedback": {
|
||||
"id": 123,
|
||||
"createdAt": "2024-01-15T10:30:00.000Z",
|
||||
"updatedAt": "2024-01-15T10:30:00.000Z",
|
||||
"message": "User feedback content",
|
||||
"userEmail": "user@example.com",
|
||||
"issues": [
|
||||
{
|
||||
"id": 456,
|
||||
"createdAt": "2024-01-15T10:30:00.000Z",
|
||||
"updatedAt": "2024-01-15T10:30:00.000Z",
|
||||
"name": "Bug Report",
|
||||
"description": "Issue description",
|
||||
"status": "OPEN",
|
||||
"externalIssueId": "EXT-123",
|
||||
"feedbackCount": 5
|
||||
}
|
||||
]
|
||||
},
|
||||
"channel": {
|
||||
"id": 1,
|
||||
"name": "Website Feedback"
|
||||
},
|
||||
"project": {
|
||||
"id": 1,
|
||||
"name": "My Project"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 2. ISSUE_CREATION
|
||||
|
||||
Occurs when a new issue is created.
|
||||
|
||||
**Payload Example:**
|
||||
|
||||
```json
|
||||
{
|
||||
"event": "ISSUE_CREATION",
|
||||
"data": {
|
||||
"issue": {
|
||||
"id": 789,
|
||||
"createdAt": "2024-01-15T11:00:00.000Z",
|
||||
"updatedAt": "2024-01-15T11:00:00.000Z",
|
||||
"name": "New Issue",
|
||||
"description": "Issue description",
|
||||
"status": "OPEN",
|
||||
"externalIssueId": "EXT-789",
|
||||
"feedbackCount": 0
|
||||
},
|
||||
"project": {
|
||||
"id": 1,
|
||||
"name": "My Project"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 3. ISSUE_STATUS_CHANGE
|
||||
|
||||
Occurs when issue status is changed.
|
||||
|
||||
**Payload Example:**
|
||||
|
||||
```json
|
||||
{
|
||||
"event": "ISSUE_STATUS_CHANGE",
|
||||
"data": {
|
||||
"issue": {
|
||||
"id": 789,
|
||||
"createdAt": "2024-01-15T11:00:00.000Z",
|
||||
"updatedAt": "2024-01-15T12:00:00.000Z",
|
||||
"name": "Issue Name",
|
||||
"description": "Issue description",
|
||||
"status": "IN_PROGRESS",
|
||||
"externalIssueId": "EXT-789",
|
||||
"feedbackCount": 3
|
||||
},
|
||||
"project": {
|
||||
"id": 1,
|
||||
"name": "My Project"
|
||||
},
|
||||
"previousStatus": "OPEN"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 4. ISSUE_ADDITION
|
||||
|
||||
Occurs when an issue is added to feedback.
|
||||
|
||||
**Payload Example:**
|
||||
|
||||
```json
|
||||
{
|
||||
"event": "ISSUE_ADDITION",
|
||||
"data": {
|
||||
"feedback": {
|
||||
"id": 123,
|
||||
"createdAt": "2024-01-15T10:30:00.000Z",
|
||||
"updatedAt": "2024-01-15T10:30:00.000Z",
|
||||
"message": "User feedback content",
|
||||
"issues": [
|
||||
{
|
||||
"id": 456,
|
||||
"name": "Existing Issue",
|
||||
"status": "OPEN"
|
||||
},
|
||||
{
|
||||
"id": 789,
|
||||
"name": "Newly Added Issue",
|
||||
"status": "OPEN"
|
||||
}
|
||||
]
|
||||
},
|
||||
"channel": {
|
||||
"id": 1,
|
||||
"name": "Website Feedback"
|
||||
},
|
||||
"project": {
|
||||
"id": 1,
|
||||
"name": "My Project"
|
||||
},
|
||||
"addedIssue": {
|
||||
"id": 789,
|
||||
"createdAt": "2024-01-15T11:00:00.000Z",
|
||||
"updatedAt": "2024-01-15T11:00:00.000Z",
|
||||
"name": "Newly Added Issue",
|
||||
"description": "Issue description",
|
||||
"status": "OPEN",
|
||||
"externalIssueId": "EXT-456",
|
||||
"feedbackCount": 1
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Webhook Receiving Server Implementation
|
||||
|
||||
You need to implement an HTTP server to receive webhooks. The server must meet the following requirements:
|
||||
|
||||
### Basic Requirements
|
||||
|
||||
1. **HTTP POST Request Handling**: Webhooks are sent via HTTP POST
|
||||
2. **JSON Payload Parsing**: Request body is in JSON format
|
||||
3. **Return 200 Response Code**: Must respond with 200 status code on successful processing
|
||||
|
||||
### Implementation Example (Node.js/Express)
|
||||
|
||||
```javascript
|
||||
const express = require('express');
|
||||
const app = express();
|
||||
|
||||
app.use(express.json());
|
||||
|
||||
app.post('/webhook', (req, res) => {
|
||||
const { event, data } = req.body;
|
||||
const token = req.headers['x-webhook-token'];
|
||||
|
||||
// Token verification
|
||||
if (token !== 'your-secret-token') {
|
||||
return res.status(401).json({ error: 'Unauthorized' });
|
||||
}
|
||||
|
||||
// Event processing
|
||||
switch (event) {
|
||||
case 'FEEDBACK_CREATION':
|
||||
console.log('New feedback created:', data.feedback);
|
||||
// Feedback processing logic
|
||||
break;
|
||||
case 'ISSUE_CREATION':
|
||||
console.log('New issue created:', data.issue);
|
||||
// Issue processing logic
|
||||
break;
|
||||
case 'ISSUE_STATUS_CHANGE':
|
||||
console.log(
|
||||
'Issue status changed:',
|
||||
data.issue,
|
||||
'Previous status:',
|
||||
data.previousStatus,
|
||||
);
|
||||
// Status change processing logic
|
||||
break;
|
||||
case 'ISSUE_ADDITION':
|
||||
console.log('Issue added:', data.addedIssue);
|
||||
// Issue addition processing logic
|
||||
break;
|
||||
}
|
||||
|
||||
res.status(200).json({ success: true });
|
||||
});
|
||||
|
||||
app.listen(3000, () => {
|
||||
console.log('Webhook listener server running on port 3000.');
|
||||
});
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Security and Retry Policy
|
||||
|
||||
### Security Considerations
|
||||
|
||||
- **Token Verification**: Verify requests through `x-webhook-token` header
|
||||
- **HTTPS Usage**: Always use HTTPS in production environments
|
||||
|
||||
### Retry Policy
|
||||
|
||||
- **Automatic Retry**: ABC User Feedback automatically retries up to 3 times on webhook transmission failure
|
||||
- **Retry Interval**: Each retry is executed after 3 seconds
|
||||
|
||||
### Error Handling
|
||||
|
||||
- **4xx Errors**: Considered client errors, not retried
|
||||
- **5xx Errors**: Considered server errors, retried
|
||||
- **Network Errors**: Retried on connection failure
|
||||
|
||||
---
|
||||
|
||||
## Usage Examples
|
||||
|
||||
### 1. Automatic Translation
|
||||
|
||||
```javascript
|
||||
// Receive FEEDBACK_CREATION event and automatically translate
|
||||
if (event === 'FEEDBACK_CREATION') {
|
||||
const translatedMessage = await translateText(data.feedback.message);
|
||||
// Update feedback with translated content
|
||||
await updateFeedback(data.feedback.id, { translatedMessage });
|
||||
}
|
||||
```
|
||||
|
||||
### 2. External Ticket System Integration
|
||||
|
||||
```javascript
|
||||
// Receive ISSUE_CREATION event and create ticket in external system
|
||||
if (event === 'ISSUE_CREATION') {
|
||||
const ticketId = await createExternalTicket({
|
||||
title: data.issue.name,
|
||||
description: data.issue.description,
|
||||
priority: 'medium',
|
||||
});
|
||||
// Store external ticket ID in issue
|
||||
await updateIssue(data.issue.id, { externalIssueId: ticketId });
|
||||
}
|
||||
```
|
||||
|
||||
### 3. Notification System Integration
|
||||
|
||||
```javascript
|
||||
// Receive ISSUE_STATUS_CHANGE event and notify team
|
||||
if (event === 'ISSUE_STATUS_CHANGE') {
|
||||
await sendSlackNotification({
|
||||
channel: '#feedback-alerts',
|
||||
message: `Issue "${data.issue.name}" status changed from ${data.previousStatus} to ${data.issue.status}.`,
|
||||
});
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Related Documents
|
||||
|
||||
- [Webhook Management](/en/user-guide/settings/webhook-management) - How to configure webhooks in UI
|
||||
- [API Integration](./02-api-integration.md) - API usage that can be used with webhooks
|
||||
- [Issue Management](/en/user-guide/issue-management) - Understanding issue status change events
|
||||
|
||||
+5
@@ -0,0 +1,5 @@
|
||||
{
|
||||
"position": 3,
|
||||
"label": "Developer Guide"
|
||||
}
|
||||
|
||||
@@ -0,0 +1,7 @@
|
||||
---
|
||||
title: Developer Guide
|
||||
---
|
||||
|
||||
import DocCardList from '@theme/DocCardList';
|
||||
|
||||
<DocCardList />
|
||||
Reference in New Issue
Block a user