Skip to content

Commit 03f4c56

Browse files
authored
feat(doc): add Forest systemd installation guide (#6491)
1 parent 323e119 commit 03f4c56

File tree

1 file changed

+129
-0
lines changed

1 file changed

+129
-0
lines changed

docs/docs/users/getting_started/install.md

Lines changed: 129 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -122,5 +122,134 @@ Sample output:
122122
forest-filecoin 0.19.0+git.671c30c
123123
```
124124

125+
</TabItem>
126+
<TabItem value="systemd" label="Systemd Unit Setup">
127+
128+
<h3>Running Forest as a `systemd` Service</h3>
129+
130+
This guide shows how to configure Forest to automatically restart on failure and start on system boot using `systemd`.
131+
132+
<h4>Prerequisites</h4>
133+
134+
- Forest must be installed and available in your `PATH` (see other tabs for installation). This guide assumes the `forest` binary is located at `/usr/local/bin/forest`.
135+
- You are running commands as `root` or with `sudo` privileges
136+
- `vi` editor. If you're using `nano`, reconsider your life choices and career path.
137+
138+
<h4>Step 1: Create a `systemd` Service File</h4>
139+
140+
Create a new service file for Forest:
141+
142+
```shell
143+
vi /etc/systemd/system/forest.service
144+
```
145+
146+
Add the following content (adjust paths and options as needed):
147+
148+
```ini
149+
[Unit]
150+
Description=Forest Filecoin Node
151+
After=network-online.target
152+
Wants=network-online.target
153+
154+
[Service]
155+
Type=simple
156+
User=forest
157+
Group=forest
158+
# Adjust the forest binary path if needed (check with: which forest)
159+
# You might want to encrypt the keystore in production with `--encrypt-keystore true` and using, e.g., `systemd-creds`
160+
ExecStart=/usr/local/bin/forest --chain calibnet --auto-download-snapshot --encrypt-keystore false --rpc-address=127.0.0.1:1234
161+
# Or for mainnet:
162+
# ExecStart=/usr/local/bin/forest --encrypt-keystore false
163+
164+
# Restart policy
165+
Restart=on-failure
166+
RestartSec=10s
167+
168+
Environment=FOREST_CHAIN_INDEXER_ENABLED=1
169+
# Optional, if F3 is not working properly.
170+
# Environment=FOREST_F3_SIDECAR_FFI_ENABLED=0
171+
172+
[Install]
173+
WantedBy=multi-user.target
174+
```
175+
176+
:::tip
177+
For production mainnet nodes, consider creating a dedicated `forest` user for better security isolation. For development/testing, you can use your own user.
178+
:::
179+
180+
<h4>Step 2: Create a Dedicated User (Optional but Recommended)</h4>
181+
182+
If you specified `User=forest` in the service file, create the user:
183+
184+
```shell
185+
adduser forest
186+
```
187+
188+
Make sure the binary is accessible by this user.
189+
190+
<h4>Step 3: Enable and Start the Service</h4>
191+
192+
Reload `systemd` to recognize the new service:
193+
194+
```shell
195+
systemctl daemon-reload
196+
```
197+
198+
Enable the service to start on boot:
199+
200+
```shell
201+
systemctl enable forest
202+
```
203+
204+
Start the service immediately:
205+
206+
```shell
207+
systemctl start forest
208+
```
209+
210+
<h4>Step 4: Verify the Service is Running</h4>
211+
212+
Check the service status:
213+
214+
```shell
215+
systemctl status forest
216+
```
217+
218+
Sample output:
219+
220+
```console
221+
● forest.service - Forest Filecoin Node
222+
Loaded: loaded (/etc/systemd/system/forest.service; enabled; vendor preset: enabled)
223+
Active: active (running) since Wed 2026-01-28 10:30:15 UTC; 2min ago
224+
Main PID: 12345 (forest)
225+
```
226+
227+
<h4>Step 5: View Logs</h4>
228+
229+
View real-time logs:
230+
231+
```shell
232+
journalctl -u forest -f
233+
```
234+
235+
View recent logs:
236+
237+
```shell
238+
journalctl -u forest -n 100
239+
```
240+
241+
<h4>Troubleshooting</h4>
242+
243+
If the service fails to start:
244+
245+
1. Check logs with `journalctl -u forest -n 50`
246+
2. Verify the `forest` binary path with `which forest`
247+
3. Ensure the user has appropriate permissions
248+
4. Check that required directories exist and are writable
249+
250+
:::note
251+
The `Restart=on-failure` option ensures Forest automatically restarts if it crashes. The `RestartSec=10s` adds a 10-second delay between restart attempts to prevent rapid restart loops.
252+
:::
253+
125254
</TabItem>
126255
</Tabs>

0 commit comments

Comments
 (0)