Skip to content

Commit 78c4069

Browse files
clovisclovis
committed
add Mac specific documentation
1 parent b1d041f commit 78c4069

3 files changed

Lines changed: 211 additions & 12 deletions

File tree

‎com.philologic5.gunicorn.plist‎

Lines changed: 43 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,43 @@
1+
<?xml version="1.0" encoding="UTF-8"?>
2+
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN"
3+
"http://www.apple.com/DTDs/PropertyList-1.0.dtd">
4+
<plist version="1.0">
5+
<dict>
6+
<key>Label</key>
7+
<string>com.philologic5.gunicorn</string>
8+
9+
<key>UserName</key>
10+
<string>__WEB_USER__</string>
11+
12+
<key>ProgramArguments</key>
13+
<array>
14+
<string>/var/lib/philologic5/philologic_env/bin/gunicorn</string>
15+
<string>--config</string>
16+
<string>/var/lib/philologic5/web_app/gunicorn.conf.py</string>
17+
<string>app:application</string>
18+
</array>
19+
20+
<key>WorkingDirectory</key>
21+
<string>/var/lib/philologic5/web_app</string>
22+
23+
<key>RunAtLoad</key>
24+
<true/>
25+
26+
<key>KeepAlive</key>
27+
<true/>
28+
29+
<key>StandardErrorPath</key>
30+
<string>/var/log/philologic5/launchd-stderr.log</string>
31+
32+
<key>StandardOutPath</key>
33+
<string>/var/log/philologic5/launchd-stdout.log</string>
34+
35+
<key>EnvironmentVariables</key>
36+
<dict>
37+
<key>NUMBA_NUM_THREADS</key>
38+
<string>2</string>
39+
<key>NUMBA_CACHE_DIR</key>
40+
<string>/var/lib/philologic5/numba_cache</string>
41+
</dict>
42+
</dict>
43+
</plist>

‎docs/installation.md‎

Lines changed: 75 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -4,19 +4,19 @@ title: Installation
44

55
## Overview
66

7-
PhiloLogic5 runs as a Gunicorn WSGI application behind a reverse proxy (Apache or Nginx). The installer handles Python, Node.js, and all Python dependencies automatically via [uv](https://docs.astral.sh/uv/).
7+
PhiloLogic5 runs as a Gunicorn WSGI application. On Linux it typically runs behind a reverse proxy (Apache or Nginx); on macOS it can bind directly to a TCP port. The installer handles Python, Node.js, and all Python dependencies automatically via [uv](https://docs.astral.sh/uv/).
88

99
Installation steps:
1010

1111
1. Install system dependencies
1212
2. Run `install.sh`
1313
3. Configure `/etc/philologic/philologic5.cfg`
14-
4. Set up your web server as a reverse proxy
14+
4. Set up your web server as a reverse proxy (Linux) or configure a TCP port (macOS)
1515
5. Enable and start the Gunicorn service
1616

1717
## System Requirements
1818

19-
- Linux (Ubuntu 22.04+, Debian 12+, RHEL 9+, or similar)
19+
- Linux (Ubuntu 22.04+, Debian 12+, RHEL 9+, or similar) or macOS (Apple Silicon or Intel)
2020
- Python 3.11+ (the installer downloads its own Python via uv by default)
2121
- Root/sudo access for installing to `/var/lib/philologic5/`
2222

@@ -39,11 +39,23 @@ sudo dnf install -y \
3939
lz4 ripgrep curl
4040
```
4141

42+
### macOS
43+
44+
```bash
45+
brew install lz4 ripgrep
46+
```
47+
48+
Xcode Command Line Tools are also required (for C compiler headers used by `lxml`):
49+
50+
```bash
51+
xcode-select --install
52+
```
53+
4254
**Notes:**
43-
- `libxml2-dev`/`libxslt-dev`/`zlib1g-dev`: required for building `lxml` (XML parsing)
55+
- `libxml2-dev`/`libxslt-dev`/`zlib1g-dev`: required for building `lxml` (XML parsing). On macOS these are provided by Xcode Command Line Tools.
4456
- `liblz4-tool`/`lz4`: used at database load time for compressing word indexes
4557
- `ripgrep`: used at database load time for filtering parser output
46-
- `curl`: used by the installer to download [uv](https://docs.astral.sh/uv/) and [nvm](https://github.com/nvm-sh/nvm)
58+
- `curl`: used by the installer to download [uv](https://docs.astral.sh/uv/) and [nvm](https://github.com/nvm-sh/nvm). Pre-installed on macOS.
4759
- The installer downloads its own Python via uv, so system Python packages are not required
4860

4961
## Installing PhiloLogic
@@ -86,7 +98,7 @@ The installer:
8698
7. Copies the web application to `/var/lib/philologic5/web_app/`
8799
8. Installs the `philoload5` command to `/usr/local/bin/`
88100
9. Creates the global config at `/etc/philologic/philologic5.cfg` (if it doesn't exist)
89-
10. Installs a systemd service file for Gunicorn
101+
10. Installs a systemd service file for Gunicorn (Linux) or a launchd plist (macOS)
90102

91103
### Installation Layout
92104

@@ -121,18 +133,30 @@ database_root = "/var/www/html/philologic5/"
121133
url_root = "http://localhost/philologic5/"
122134
```
123135

136+
On macOS, typical values would be:
137+
138+
```python
139+
database_root = "/Library/WebServer/Documents/philologic/"
140+
url_root = "http://localhost:8080/"
141+
```
142+
124143
Make sure the `database_root` directory exists and is writable by your user:
125144

126145
```bash
127-
sudo mkdir -p /var/www/html/philologic5
128-
sudo chown -R $USER:$USER /var/www/html/philologic5
146+
sudo mkdir -p /var/www/html/philologic5 # Linux
147+
# or
148+
sudo mkdir -p /Library/WebServer/Documents/philologic # macOS
149+
150+
sudo chown -R $USER:$USER <database_root>
129151
```
130152

131153
## Web Server Configuration
132154

133-
PhiloLogic5 runs behind Gunicorn, which listens on a Unix socket. You need a reverse proxy (Apache or Nginx) to forward HTTP requests to Gunicorn.
155+
### Linux
134156

135-
### Starting Gunicorn
157+
On Linux, PhiloLogic5 runs behind Gunicorn, which listens on a Unix socket. You need a reverse proxy (Apache or Nginx) to forward HTTP requests to Gunicorn.
158+
159+
#### Starting Gunicorn
136160

137161
```bash
138162
sudo systemctl enable philologic5-gunicorn
@@ -146,7 +170,42 @@ sudo systemctl status philologic5-gunicorn
146170
journalctl -u philologic5-gunicorn -f # follow logs
147171
```
148172

149-
### Apache
173+
### macOS
174+
175+
On macOS, the simplest setup is to bind Gunicorn directly to a TCP port (no reverse proxy needed). Edit `/var/lib/philologic5/web_app/gunicorn.conf.py` and change the `bind` setting:
176+
177+
```python
178+
bind = "127.0.0.1:8080"
179+
```
180+
181+
Make sure the port matches the one in your `url_root` in `/etc/philologic/philologic5.cfg`.
182+
183+
You can then start Gunicorn manually:
184+
185+
```bash
186+
/var/lib/philologic5/philologic_env/bin/gunicorn \
187+
--config /var/lib/philologic5/web_app/gunicorn.conf.py \
188+
app:application
189+
```
190+
191+
Or use the installed launchd plist for automatic startup:
192+
193+
```bash
194+
sudo cp /var/lib/philologic5/com.philologic5.gunicorn.plist /Library/LaunchDaemons/
195+
sudo launchctl bootstrap system /Library/LaunchDaemons/com.philologic5.gunicorn.plist
196+
```
197+
198+
To stop or restart:
199+
200+
```bash
201+
# Restart (launchd will relaunch automatically since KeepAlive is set)
202+
sudo launchctl kill SIGTERM system/com.philologic5.gunicorn
203+
204+
# Stop completely
205+
sudo launchctl bootout system/com.philologic5.gunicorn
206+
```
207+
208+
### Apache (Linux)
150209

151210
Enable the required modules:
152211

@@ -167,7 +226,7 @@ ProxyTimeout 300
167226
</Location>
168227
```
169228

170-
### Nginx
229+
### Nginx (Linux)
171230

172231
Add to your `server` block:
173232

@@ -225,5 +284,9 @@ The installer will remove and recreate `/var/lib/philologic5/` but preserves you
225284
After upgrading, restart Gunicorn:
226285

227286
```bash
287+
# Linux
228288
sudo systemctl restart philologic5-gunicorn
289+
290+
# macOS (launchd restarts automatically via KeepAlive)
291+
sudo launchctl kill SIGTERM system/com.philologic5.gunicorn
229292
```

‎docs/specific_installations/macos_installation.md‎

Lines changed: 93 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,93 @@
1+
---
2+
title: Installing PhiloLogic5 on macOS
3+
---
4+
5+
Tested on macOS Ventura and later (Apple Silicon and Intel).
6+
7+
### 1. Install System Dependencies
8+
9+
Install [Homebrew](https://brew.sh/) if you don't already have it, then:
10+
11+
```bash
12+
brew install lz4 ripgrep
13+
xcode-select --install # if not already installed
14+
```
15+
16+
### 2. Run the Installer
17+
18+
```bash
19+
cd PhiloLogic5
20+
sudo ./install.sh
21+
```
22+
23+
The installer automatically detects macOS and adjusts user/group ownership accordingly.
24+
25+
### 3. Configure PhiloLogic
26+
27+
Edit `/etc/philologic/philologic5.cfg`:
28+
29+
```python
30+
database_root = "/Library/WebServer/Documents/philologic/"
31+
url_root = "http://localhost:8080/"
32+
```
33+
34+
Create the database directory:
35+
36+
```bash
37+
sudo mkdir -p /Library/WebServer/Documents/philologic
38+
sudo chown -R $USER:staff /Library/WebServer/Documents/philologic
39+
```
40+
41+
### 4. Configure Gunicorn for Direct Access
42+
43+
On macOS, the simplest setup is to bind Gunicorn directly to a TCP port instead of a Unix socket. Edit `/var/lib/philologic5/web_app/gunicorn.conf.py` and change:
44+
45+
```python
46+
bind = "127.0.0.1:8080"
47+
```
48+
49+
Make sure the port matches the one in your `url_root` above. This customization is preserved across reinstalls.
50+
51+
### 5. Start Gunicorn
52+
53+
You can run Gunicorn directly:
54+
55+
```bash
56+
/var/lib/philologic5/philologic_env/bin/gunicorn \
57+
--config /var/lib/philologic5/web_app/gunicorn.conf.py \
58+
app:application
59+
```
60+
61+
Or install the launchd service for automatic startup:
62+
63+
```bash
64+
sudo cp /var/lib/philologic5/com.philologic5.gunicorn.plist /Library/LaunchDaemons/
65+
sudo launchctl bootstrap system /Library/LaunchDaemons/com.philologic5.gunicorn.plist
66+
```
67+
68+
### 6. Verify
69+
70+
PhiloLogic5 should now be accessible at `http://localhost:8080/`. Load a database with `philoload5` and navigate to it.
71+
72+
### Managing the Service
73+
74+
```bash
75+
# Restart (launchd relaunches automatically via KeepAlive)
76+
sudo launchctl kill SIGTERM system/com.philologic5.gunicorn
77+
78+
# Stop completely
79+
sudo launchctl bootout system/com.philologic5.gunicorn
80+
81+
# Re-enable after stopping
82+
sudo launchctl bootstrap system /Library/LaunchDaemons/com.philologic5.gunicorn.plist
83+
```
84+
85+
### Differences from Linux
86+
87+
| | Linux | macOS |
88+
|---|---|---|
89+
| Service manager | systemd | launchd |
90+
| Gunicorn bind | Unix socket (via reverse proxy) | TCP port (direct access) |
91+
| Web server user | `www-data` | Current user |
92+
| Typical `database_root` | `/var/www/html/philologic5/` | `/Library/WebServer/Documents/philologic/` |
93+
| Reverse proxy | Required (Apache/Nginx) | Optional |

0 commit comments

Comments
 (0)