LeafOK_CVS/lbbs/INSTALL.md

# Installation

The Chinese version of this installation guide is available at [INSTALL.zh_CN.md](INSTALL.zh_CN.md).

To install LBBS on Linux (e.g., Debian 13, CentOS Stream 10), please perform the following steps:

## 0. Prerequisites

Follow the instructions in [leafok_bbs](https://github.com/leafok/leafok_bbs) README.md to initialize the database structure shared by both the web and telnet versions.

It is highly recommended to complete the web version configuration steps first and ensure those features work properly.

## 1. Common Requirements

- gcc >= 13.3
- autoconf >= 2.68
- automake >= 1.16
- php >= 8.2
- mysql >= 8.4

### Distribution-Specific Packages

**Debian / Ubuntu:**
```bash
sudo apt-get install -y libssh-dev libsystemd-dev
```

**CentOS / RHEL:**
```bash
sudo dnf install -y libssh-devel systemd-devel
```

**MSYS2 with MinGW-w64 toolchain:**
```bash
pacman -S --needed msys2-runtime-devel libssh libssh-devel pcre2-devel mingw-w64-x86_64-libiconv mingw-w64-x86_64-libmariadbclient
```

## 2. Extract Source Files

Extract the source files from a tarball or export from GitHub.

Run the following command to set up the autoconf/automake environment:
```bash
autoreconf --install --force
```

## 3. Compile Source Files

```bash
export LBBS_HOME_DIR=/usr/local/lbbs
```

**For Linux:**
```bash
./configure --prefix=$LBBS_HOME_DIR
```

**For MSYS2 with MinGW-w64 toolchain:**
```bash
./configure --prefix=$LBBS_HOME_DIR --disable-shared PKG_CONFIG_PATH=/mingw64/lib/pkgconfig/
```

```bash
make
```

## 4. Create User and Group

```bash
sudo useradd bbs
```

## 5. Install Binary and Data Files

```bash
sudo make install
chown -R bbs:bbs $LBBS_HOME_DIR
```

## 6. Modify Configuration Files

Default configuration files are saved as `*.default`. Copy and rename them first:

```bash
cd $LBBS_HOME_DIR
cp conf/bbsd.conf.default conf/bbsd.conf
cp conf/bbsnet.conf.default conf/bbsnet.conf
cp conf/badwords.conf.default conf/badwords.conf
cp utils/conf/db_conn.conf.php.default utils/conf/db_conn.conf.php
```

Then edit each file to match your environment:

### bbsd.conf
Key settings to adjust:
- `db_host`, `db_username`, `db_password`, `db_database`: MySQL connection details
- `bbs_server`, `bbs_port`, `bbs_ssh_port`: Network settings
- `bbs_name`: Your BBS name
- `bbs_max_client`: Maximum concurrent connections (adjust based on server capacity)

### db_conn.conf.php
Set the database connection parameters:
- `$DB_hostname`, `$DB_username`, `$DB_password`, `$DB_database`

### bbsnet.conf & badwords.conf
Review and customize as needed for your BBS policies.

## 7. Copy MySQL CA Certificate

Copy the MySQL server's CA certificate file to `$LBBS_HOME_DIR/conf/ca_cert.pem`.

## 8. Generate Menu Configuration Files

Run the following scripts to generate menu configuration files with section data:

```bash
sudo -u bbs php $LBBS_HOME_DIR/utils/bin/gen_section_menu.php
sudo -u bbs php $LBBS_HOME_DIR/utils/bin/gen_ex_list.php
sudo -u bbs php $LBBS_HOME_DIR/utils/bin/gen_top.php
```

## 9. Create SSH2 Certificates

Generate SSH host keys for the SSH server component. The `-N ""` flag sets an empty passphrase for the keys (required for automated service startup).

```bash
ssh-keygen -t rsa -C "Your Server Name" -N "" -f $LBBS_HOME_DIR/conf/ssh_host_rsa_key
ssh-keygen -t ed25519 -C "Your Server Name" -N "" -f $LBBS_HOME_DIR/conf/ssh_host_ed25519_key
ssh-keygen -t ecdsa -C "Your Server Name" -N "" -f $LBBS_HOME_DIR/conf/ssh_host_ecdsa_key
```

## 10. Startup

```bash
sudo -u bbs $LBBS_HOME_DIR/bin/bbsd
```

## 11. (Optional) Set Up systemd

Create your own `/usr/lib/systemd/system/lbbs.service` from the sample at `conf/lbbs.service`, and make any necessary changes.

Reload daemon configuration and start the service.

## 12. (Optional) Set Up logrotate

Create your own `/etc/logrotate.d/lbbs` from the sample at `conf/lbbs.logrotate`, and make any necessary changes.

Restart the logrotate service.

## 13. Cleanup on Abnormal Service Termination

In case of unexpected failure or improper operation resulting in abnormal termination of the LBBS process, manual cleanup of shared memory/semaphore might be required before relaunching the process.

### When Cleanup is Needed
- After a crash or force-kill of the `bbsd` process
- If `bbsd` fails to start with "shared memory already exists" errors
- When `ipcs` shows resources owned by user `bbs`

### Checking for Orphaned Resources
First, check for any remaining shared memory segments or semaphores:
```bash
sudo -u bbs ipcs
```

Look for entries in the "SHM" (shared memory) and "SEM" (semaphore) sections where the "OWNER" is `bbs`.

### Cleaning Up
If resources exist, remove them with:
```bash
sudo -u bbs ipcrm -a
```

This removes all shared memory and semaphore resources accessible to the `bbs` user.

## 14. Docker Installation (Alternative Method)

For containerized deployment, LBBS provides Docker support.

### Building from Source
To build the Docker image from source code:
```bash
docker compose up --build -d
```

### Using Pre-built Images
To use pre-built images from Docker Hub:
```bash
docker compose pull
docker compose up -d
```

### Configuration for Docker
When using Docker, you still need to configure LBBS appropriately:

1. **Configuration Files**: Create and customize the configuration files as described in Step 6.
2. **Database Connection**: Ensure `db_conn.conf.php` points to your MySQL server (which should be accessible from the container).
3. **Port Mapping**: By default, Docker Compose maps:
   - SSH port: 2322 → 2322 (container)
   - Telnet port: 2323 → 2323 (container)
   
   Adjust these in `docker-compose.yml` if needed.
4. **Persistent Data**: The `data/` and `conf/` directories are mounted as volumes for persistence.

### Docker Compose Management
- Start: `docker compose up -d`
- Stop: `docker compose down`
- View logs: `docker compose logs -f`
- Restart: `docker compose restart`

For more details, refer to the `docker-compose.yml` file and Docker documentation.
1	sysadm	1.31	# Installation
2	sysadm	1.29
3	sysadm	1.32	The Chinese version of this installation guide is available at [INSTALL.zh_CN.md](INSTALL.zh_CN.md).
4	sysadm	1.29
5	sysadm	1.31	To install LBBS on Linux (e.g., Debian 13, CentOS Stream 10), please perform the following steps:
6
7			## 0. Prerequisites
8
9			Follow the instructions in [leafok_bbs](https://github.com/leafok/leafok_bbs) README.md to initialize the database structure shared by both the web and telnet versions.
10
11			It is highly recommended to complete the web version configuration steps first and ensure those features work properly.
12
13			## 1. Common Requirements
14
15			- gcc >= 13.3
16			- autoconf >= 2.68
17			- automake >= 1.16
18			- php >= 8.2
19			- mysql >= 8.4
20
21			### Distribution-Specific Packages
22
23			Debian / Ubuntu:
24			```bash
25			sudo apt-get install -y libssh-dev libsystemd-dev
26			```
27
28			CentOS / RHEL:
29			```bash
30			sudo dnf install -y libssh-devel systemd-devel
31			```
32
33			MSYS2 with MinGW-w64 toolchain:
34			```bash
35			pacman -S --needed msys2-runtime-devel libssh libssh-devel pcre2-devel mingw-w64-x86_64-libiconv mingw-w64-x86_64-libmariadbclient
36			```
37
38			## 2. Extract Source Files
39
40			Extract the source files from a tarball or export from GitHub.
41
42			Run the following command to set up the autoconf/automake environment:
43			```bash
44			autoreconf --install --force
45			```
46
47			## 3. Compile Source Files
48
49			```bash
50			export LBBS_HOME_DIR=/usr/local/lbbs
51			```
52
53			For Linux:
54			```bash
55			./configure --prefix=$LBBS_HOME_DIR
56			```
57
58			For MSYS2 with MinGW-w64 toolchain:
59			```bash
60			./configure --prefix=$LBBS_HOME_DIR --disable-shared PKG_CONFIG_PATH=/mingw64/lib/pkgconfig/
61			```
62
63			```bash
64			make
65			```
66
67			## 4. Create User and Group
68
69			```bash
70			sudo useradd bbs
71			```
72
73			## 5. Install Binary and Data Files
74
75			```bash
76			sudo make install
77			chown -R bbs:bbs $LBBS_HOME_DIR
78			```
79
80			## 6. Modify Configuration Files
81
82	sysadm	1.32	Default configuration files are saved as `*.default`. Copy and rename them first:
83	sysadm	1.31
84	sysadm	1.32	```bash
85			cd $LBBS_HOME_DIR
86			cp conf/bbsd.conf.default conf/bbsd.conf
87			cp conf/bbsnet.conf.default conf/bbsnet.conf
88			cp conf/badwords.conf.default conf/badwords.conf
89			cp utils/conf/db_conn.conf.php.default utils/conf/db_conn.conf.php
90			```
91
92			Then edit each file to match your environment:
93
94			### bbsd.conf
95			Key settings to adjust:
96			- `db_host`, `db_username`, `db_password`, `db_database`: MySQL connection details
97			- `bbs_server`, `bbs_port`, `bbs_ssh_port`: Network settings
98			- `bbs_name`: Your BBS name
99			- `bbs_max_client`: Maximum concurrent connections (adjust based on server capacity)
100
101			### db_conn.conf.php
102			Set the database connection parameters:
103			- `$DB_hostname`, `$DB_username`, `$DB_password`, `$DB_database`
104
105			### bbsnet.conf & badwords.conf
106			Review and customize as needed for your BBS policies.
107	sysadm	1.31
108			## 7. Copy MySQL CA Certificate
109
110			Copy the MySQL server's CA certificate file to `$LBBS_HOME_DIR/conf/ca_cert.pem`.
111
112			## 8. Generate Menu Configuration Files
113
114			Run the following scripts to generate menu configuration files with section data:
115
116			```bash
117			sudo -u bbs php $LBBS_HOME_DIR/utils/bin/gen_section_menu.php
118			sudo -u bbs php $LBBS_HOME_DIR/utils/bin/gen_ex_list.php
119			sudo -u bbs php $LBBS_HOME_DIR/utils/bin/gen_top.php
120			```
121
122			## 9. Create SSH2 Certificates
123
124	sysadm	1.32	Generate SSH host keys for the SSH server component. The `-N ""` flag sets an empty passphrase for the keys (required for automated service startup).
125
126	sysadm	1.31	```bash
127			ssh-keygen -t rsa -C "Your Server Name" -N "" -f $LBBS_HOME_DIR/conf/ssh_host_rsa_key
128			ssh-keygen -t ed25519 -C "Your Server Name" -N "" -f $LBBS_HOME_DIR/conf/ssh_host_ed25519_key
129			ssh-keygen -t ecdsa -C "Your Server Name" -N "" -f $LBBS_HOME_DIR/conf/ssh_host_ecdsa_key
130			```
131
132			## 10. Startup
133
134			```bash
135			sudo -u bbs $LBBS_HOME_DIR/bin/bbsd
136			```
137
138			## 11. (Optional) Set Up systemd
139
140			Create your own `/usr/lib/systemd/system/lbbs.service` from the sample at `conf/lbbs.service`, and make any necessary changes.
141
142			Reload daemon configuration and start the service.
143
144			## 12. (Optional) Set Up logrotate
145
146			Create your own `/etc/logrotate.d/lbbs` from the sample at `conf/lbbs.logrotate`, and make any necessary changes.
147
148			Restart the logrotate service.
149
150			## 13. Cleanup on Abnormal Service Termination
151
152			In case of unexpected failure or improper operation resulting in abnormal termination of the LBBS process, manual cleanup of shared memory/semaphore might be required before relaunching the process.
153
154	sysadm	1.32	### When Cleanup is Needed
155			- After a crash or force-kill of the `bbsd` process
156			- If `bbsd` fails to start with "shared memory already exists" errors
157			- When `ipcs` shows resources owned by user `bbs`
158
159			### Checking for Orphaned Resources
160			First, check for any remaining shared memory segments or semaphores:
161	sysadm	1.31	```bash
162			sudo -u bbs ipcs
163			```
164
165	sysadm	1.32	Look for entries in the "SHM" (shared memory) and "SEM" (semaphore) sections where the "OWNER" is `bbs`.
166
167			### Cleaning Up
168			If resources exist, remove them with:
169	sysadm	1.31	```bash
170			sudo -u bbs ipcrm -a
171			```
172
173	sysadm	1.32	This removes all shared memory and semaphore resources accessible to the `bbs` user.
174
175			## 14. Docker Installation (Alternative Method)
176	sysadm	1.31
177	sysadm	1.32	For containerized deployment, LBBS provides Docker support.
178
179			### Building from Source
180			To build the Docker image from source code:
181	sysadm	1.31	```bash
182			docker compose up --build -d
183			```
184
185	sysadm	1.32	### Using Pre-built Images
186			To use pre-built images from Docker Hub:
187	sysadm	1.31	```bash
188			docker compose pull
189	sysadm	1.32	docker compose up -d
190	sysadm	1.31	```
191
192	sysadm	1.32	### Configuration for Docker
193			When using Docker, you still need to configure LBBS appropriately:
194
195			1. Configuration Files: Create and customize the configuration files as described in Step 6.
196			2. Database Connection: Ensure `db_conn.conf.php` points to your MySQL server (which should be accessible from the container).
197			3. Port Mapping: By default, Docker Compose maps:
198			- SSH port: 2322 → 2322 (container)
199			- Telnet port: 2323 → 2323 (container)
200
201			Adjust these in `docker-compose.yml` if needed.
202			4. Persistent Data: The `data/` and `conf/` directories are mounted as volumes for persistence.
203
204			### Docker Compose Management
205			- Start: `docker compose up -d`
206			- Stop: `docker compose down`
207			- View logs: `docker compose logs -f`
208			- Restart: `docker compose restart`
209
210			For more details, refer to the `docker-compose.yml` file and Docker documentation.
webmaster@leafok.com	ViewVC Help
Powered by ViewVC 1.3.0-beta1