LeafOK_CVS/fenglin/README.md

# LeafOK BBS

Chinese version: [README.zh_CN.md](README.zh_CN.md)

## Table of Contents
- [Program Overview](#program-overview)
- [Installation and Usage Instructions](#installation-and-usage-instructions)
  - [Prerequisites and Required Libraries](#1-prerequisites-and-required-libraries)
  - [Database Setup](#2-database-setup)
  - [Configuration](#3-configuration)
  - [Site Customization](#4-site-customization)
  - [Directory Permissions](#5-directory-permissions)
  - [Account Creation](#6-account-creation)
  - [Additional Database Setup](#7-database-setup-additional)
  - [Management and Background Jobs](#8-management-and-background-jobs)
- [Docker Deployment](#docker-deployment)
  - [Quick Start](#quick-start)
  - [Build from Source](#build-from-source)
  - [Using Pre-built Images](#using-pre-built-images)
  - [Configuration for Docker](#configuration-for-docker)
  - [Docker Compose Services](#docker-compose-services)
  - [Common Docker Commands](#common-docker-commands)
  - [Persistent Data](#persistent-data)
- [Copyright Information](#copyright-information)
- [License](#license)

## Program Overview

**Development Language:** PHP (8.2) + MySQL (8.4)  
**Platform:** Linux / Windows  
**License:** Source code released under GNU GPL license  

**Features:**
- Web-based article browsing, posting, searching, and other basic functions
- Support for multiple categories and sections, each with discussion areas, digest areas, and featured areas
- Comprehensive moderator management support
- **Advanced Search Capabilities:**
  - Solr-powered full-text search with Chinese language support
- **Modern Architecture:**
  - Refactored Lightweight Markup Language (LML) renderer with improved performance
  - User timezone support for localized date/time display
  - Theme support for major features
- Optional Telnet access for login, article viewing, games, etc. (see [lbbs](https://github.com/leafok/lbbs) for details)

**Demo site:** https://fenglin.info/bbs/

## Installation and Usage Instructions

### 1. Prerequisites and Required Libraries
- **PHP 8.2+** and **MySQL 8.4+** installed
- Install Composer using your package manager (e.g., `apt`, `yum`, or from [getcomposer.org](https://getcomposer.org/))
- Run the following command in the project root directory:
```bash
composer install --prefer-dist --no-scripts --no-progress
```

### 2. Database Setup
- Import the database structure from `TODO/sql/db_stru.sql`
- *(Optional)* Import sample data from `TODO/sql/sample_data.sql`
  - Test account: `sysop`
  - Temporary password (must be changed upon first login): `3anzHaNg`

### 3. Configuration
- Copy files from `TODO/conf/` directory to `conf` directory (create if it doesn't exist)
- Modify the following files:
  - Site information: Edit `conf/site.conf.php`
  - Database connection: Edit `conf/db_conn.conf.php`
  - Email sending: Edit `conf/smtp.conf.php` (supports both SMTP and local sendmail)
- **Solr search** (optional): Edit `conf/solr.conf.php` if using Solr for advanced search features
  - Default configuration assumes Solr running on `localhost:8983` with core `lbbs`
  - Update hostname, port, authentication, and path as needed
  - Import schema from `TODO/solr/schema.json` into core `lbbs`
  - Install pecl/solr extension with PIE

### 4. Site Customization
- Modify `lib/common.inc.php` for site-specific configurations

### 5. Directory Permissions
- Create directories (if they don't exist):
  - `bbs/cache`
  - `bbs/upload`
  - `export_xml`
  - `stat`
- Ensure the web server user has write permissions for:
  - `bbs/cache`
  - `bbs/upload`
  - `export_xml`
  - `gen_ex`
  - `stat`

### 6. Account Creation
- Create administrator and initial accounts through the registration page
- *Note:* Involves multiple database tables; not recommended to create directly in the database

### 7. Database Setup (Additional)
- Add administrator accounts, categories, and sections in the database
- Relevant tables: `admin_config`, `section_class`, `section_config`

### 8. Management and Background Jobs
- Management programs are located in the `manage` directory
- Scheduled background tasks require adding to crontab

## Docker Deployment

### Quick Start
```bash
# Clone the repository
git clone https://github.com/leafok/leafok_bbs.git
cd leafok_bbs

# Start with Docker Compose
docker compose up -d
```

### Build from Source
```bash
docker compose up --build -d
```

### Using Pre-built Images
```bash
# Pull the latest images from Docker Hub
docker compose pull

# Start the containers
docker compose up -d
```

### Configuration for Docker
1. The web application will be available at `http://localhost:8080`
2. Configuration files should be placed in `conf/` directory (mounted to `/var/www/html/conf` in the container)
3. To modify configuration:
   - Copy files from `TODO/conf/` to `conf/` directory
   - Edit the configuration files as needed
   - Restart the container: `docker compose restart`

### Docker Compose Services
- **web**: Apache HTTP Server with PHP 8.2
- **db**: MySQL 8.4 database
- **phpmyadmin**: Database management interface (optional, available at `http://localhost:8081`)

### Common Docker Commands
```bash
# View logs
docker compose logs -f

# Stop containers
docker compose down

# Rebuild and restart
docker compose up --build -d

# Access container shell
docker compose exec web bash
```

### Persistent Data
- Database data is stored in a Docker volume (`leafok_bbs_db_data`)
- Uploaded files and cache are stored in mounted host directories

## Copyright Information
Copyright (C) 2001-2026 Leaflet <leaflet@leafok.com>

## License
This program is free software; you can redistribute it and/or modify it under the terms of the [GNU General Public License](LICENSE) as published by the Free Software Foundation; either version 3 of the License, or (at your option) any later version.
1	sysadm	1.1	# LeafOK BBS
2
3	sysadm	1.12	Chinese version: [README.zh_CN.md](README.zh_CN.md)
4	sysadm	1.1
5	sysadm	1.14	## Table of Contents
6			- [Program Overview](#program-overview)
7			- [Installation and Usage Instructions](#installation-and-usage-instructions)
8			- [Prerequisites and Required Libraries](#1-prerequisites-and-required-libraries)
9			- [Database Setup](#2-database-setup)
10			- [Configuration](#3-configuration)
11			- [Site Customization](#4-site-customization)
12			- [Directory Permissions](#5-directory-permissions)
13			- [Account Creation](#6-account-creation)
14			- [Additional Database Setup](#7-database-setup-additional)
15			- [Management and Background Jobs](#8-management-and-background-jobs)
16			- [Docker Deployment](#docker-deployment)
17			- [Quick Start](#quick-start)
18			- [Build from Source](#build-from-source)
19			- [Using Pre-built Images](#using-pre-built-images)
20			- [Configuration for Docker](#configuration-for-docker)
21			- [Docker Compose Services](#docker-compose-services)
22			- [Common Docker Commands](#common-docker-commands)
23			- [Persistent Data](#persistent-data)
24			- [Copyright Information](#copyright-information)
25			- [License](#license)
26
27	sysadm	1.12	## Program Overview
28	sysadm	1.1
29	sysadm	1.12	Development Language: PHP (8.2) + MySQL (8.4)
30			Platform: Linux / Windows
31			License: Source code released under GNU GPL license
32
33			Features:
34			- Web-based article browsing, posting, searching, and other basic functions
35	sysadm	1.16	- Support for multiple categories and sections, each with discussion areas, digest areas, and featured areas
36			- Comprehensive moderator management support
37	sysadm	1.15	- Advanced Search Capabilities:
38			- Solr-powered full-text search with Chinese language support
39			- Modern Architecture:
40			- Refactored Lightweight Markup Language (LML) renderer with improved performance
41			- User timezone support for localized date/time display
42			- Theme support for major features
43	sysadm	1.12	- Optional Telnet access for login, article viewing, games, etc. (see [lbbs](https://github.com/leafok/lbbs) for details)
44
45			Demo site: https://fenglin.info/bbs/
46
47			## Installation and Usage Instructions
48
49	sysadm	1.14	### 1. Prerequisites and Required Libraries
50			- PHP 8.2+ and MySQL 8.4+ installed
51			- Install Composer using your package manager (e.g., `apt`, `yum`, or from [getcomposer.org](https://getcomposer.org/))
52			- Run the following command in the project root directory:
53			```bash
54			composer install --prefer-dist --no-scripts --no-progress
55			```
56
57			### 2. Database Setup
58	sysadm	1.12	- Import the database structure from `TODO/sql/db_stru.sql`
59	sysadm	1.14	- (Optional) Import sample data from `TODO/sql/sample_data.sql`
60	sysadm	1.12	- Test account: `sysop`
61	sysadm	1.14	- Temporary password (must be changed upon first login): `3anzHaNg`
62	sysadm	1.12
63	sysadm	1.14	### 3. Configuration
64	sysadm	1.12	- Copy files from `TODO/conf/` directory to `conf` directory (create if it doesn't exist)
65			- Modify the following files:
66	sysadm	1.13	- Site information: Edit `conf/site.conf.php`
67	sysadm	1.12	- Database connection: Edit `conf/db_conn.conf.php`
68			- Email sending: Edit `conf/smtp.conf.php` (supports both SMTP and local sendmail)
69	sysadm	1.16	- Solr search (optional): Edit `conf/solr.conf.php` if using Solr for advanced search features
70			- Default configuration assumes Solr running on `localhost:8983` with core `lbbs`
71			- Update hostname, port, authentication, and path as needed
72			- Import schema from `TODO/solr/schema.json` into core `lbbs`
73			- Install pecl/solr extension with PIE
74	sysadm	1.12
75	sysadm	1.14	### 4. Site Customization
76	sysadm	1.12	- Modify `lib/common.inc.php` for site-specific configurations
77
78	sysadm	1.14	### 5. Directory Permissions
79	sysadm	1.12	- Create directories (if they don't exist):
80			- `bbs/cache`
81			- `bbs/upload`
82	sysadm	1.17	- `export_xml`
83	sysadm	1.12	- `stat`
84			- Ensure the web server user has write permissions for:
85			- `bbs/cache`
86			- `bbs/upload`
87	sysadm	1.17	- `export_xml`
88	sysadm	1.12	- `gen_ex`
89			- `stat`
90
91	sysadm	1.14	### 6. Account Creation
92	sysadm	1.12	- Create administrator and initial accounts through the registration page
93			- Note: Involves multiple database tables; not recommended to create directly in the database
94
95	sysadm	1.14	### 7. Database Setup (Additional)
96	sysadm	1.12	- Add administrator accounts, categories, and sections in the database
97			- Relevant tables: `admin_config`, `section_class`, `section_config`
98
99	sysadm	1.14	### 8. Management and Background Jobs
100	sysadm	1.12	- Management programs are located in the `manage` directory
101			- Scheduled background tasks require adding to crontab
102
103	sysadm	1.14	## Docker Deployment
104
105			### Quick Start
106			```bash
107			# Clone the repository
108			git clone https://github.com/leafok/leafok_bbs.git
109			cd leafok_bbs
110
111			# Start with Docker Compose
112			docker compose up -d
113			```
114	sysadm	1.12
115			### Build from Source
116			```bash
117			docker compose up --build -d
118			```
119
120	sysadm	1.14	### Using Pre-built Images
121	sysadm	1.12	```bash
122	sysadm	1.14	# Pull the latest images from Docker Hub
123	sysadm	1.12	docker compose pull
124	sysadm	1.14
125			# Start the containers
126			docker compose up -d
127			```
128
129			### Configuration for Docker
130			1. The web application will be available at `http://localhost:8080`
131			2. Configuration files should be placed in `conf/` directory (mounted to `/var/www/html/conf` in the container)
132			3. To modify configuration:
133			- Copy files from `TODO/conf/` to `conf/` directory
134			- Edit the configuration files as needed
135			- Restart the container: `docker compose restart`
136
137			### Docker Compose Services
138			- web: Apache HTTP Server with PHP 8.2
139			- db: MySQL 8.4 database
140			- phpmyadmin: Database management interface (optional, available at `http://localhost:8081`)
141
142			### Common Docker Commands
143			```bash
144			# View logs
145			docker compose logs -f
146
147			# Stop containers
148			docker compose down
149
150			# Rebuild and restart
151			docker compose up --build -d
152
153			# Access container shell
154			docker compose exec web bash
155	sysadm	1.12	```
156	sysadm	1.1
157	sysadm	1.14	### Persistent Data
158			- Database data is stored in a Docker volume (`leafok_bbs_db_data`)
159			- Uploaded files and cache are stored in mounted host directories
160	sysadm	1.1
161	sysadm	1.12	## Copyright Information
162	sysadm	1.16	Copyright (C) 2001-2026 Leaflet <leaflet@leafok.com>
163	sysadm	1.1
164	sysadm	1.12	## License
165	sysadm	1.15	This program is free software; you can redistribute it and/or modify it under the terms of the [GNU General Public License](LICENSE) as published by the Free Software Foundation; either version 3 of the License, or (at your option) any later version.
webmaster@leafok.com	ViewVC Help
Powered by ViewVC 1.3.0-beta1