Skip to main content

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:

Downloading Source Code​

First, clone the ABC User Feedback source code from the GitHub repository:

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:

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:

pnpm install

After installing dependencies, build all packages:

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:

# 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:

NEXT_PUBLIC_API_BASE_URL=http://localhost:4000

For detailed information on environment variables, refer to the Environment Variable Settings 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:

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:

# 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:

# From project root directory
cd packages/ufb-shared
pnpm build

Building UI Packages​

Before running the web application, you need to build UI packages:

# From project root directory
cd packages/ufb-tailwindcss
pnpm build

Running Each Server Individually​

To run each server individually:

# 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:

# 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:

# 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:

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:

pnpm lint

Formatting​

To run code formatting:

pnpm format

Testing​

To run tests:

pnpm test

Swagger Documentation​

When the API server is running, you can check Swagger documentation at the following endpoints:

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.