Skip to content

Commit 6d14319

Browse files
shamanecshamanec
committed
Merge branch 'main' into develop
2 parents b7f562d + 9239e91 commit 6d14319

2 files changed

Lines changed: 94 additions & 1 deletion

File tree

‎README.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -189,7 +189,7 @@ For detailed instructions on how to create a service for Linux using systemd, pl
189189
For detailed instructions on how to create a service for Windows using WinSW, please refer to the [Windows Service Documentation](./docs/windows-service.md).
190190

191191
### 🍏 macOS
192-
*Note: Service implementation for macOS is yet to be documented.*
192+
For detailed instructions on how to create a service for macOS using launchd, please refer to the [macOS Service Documentation](./docs/macos-service.md).
193193

194194
## ❓ FAQ
195195

‎docs/macos-service.md‎

Lines changed: 93 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,93 @@
1+
# macOS Service setup
2+
You can set up GADS provider to run as a `launchd` service on macOS. This ensures the provider starts automatically on boot and restarts if it crashes.
3+
4+
## Prerequisites
5+
- Move the `gads` binary to `/usr/local/bin/gads`
6+
- Ensure the binary is executable: `sudo chmod +x /usr/local/bin/gads`
7+
- Grant **Full Disk Access** to `/usr/local/bin/gads` in **System Settings > Privacy & Security**.
8+
- **Important:** If providing only iOS devices on an Intel Mac, it is recommended to uninstall `adb` (Android Debug Bridge) to prevent potential kernel panics and USB instability.
9+
10+
## Create the service file
11+
Create a new file at `/Library/LaunchDaemons/com.gads.provider.plist`:
12+
`sudo nano /Library/LaunchDaemons/com.gads.provider.plist`
13+
14+
Paste the following configuration, adjusting the values for your environment:
15+
16+
```xml
17+
<?xml version="1.0" encoding="UTF-8"?>
18+
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "[http://www.apple.com/DTDs/PropertyList-1.0.dtd](http://www.apple.com/DTDs/PropertyList-1.0.dtd)">
19+
<plist version="1.0">
20+
<dict>
21+
<key>Label</key>
22+
<string>com.gads.provider</string>
23+
<key>ProgramArguments</key>
24+
<array>
25+
<string>/usr/local/bin/gads</string>
26+
<string>provider</string>
27+
<string>--hub</string>
28+
<string>http://___.___.___.___:PORT</string>
29+
<string>--mongo-db</string>
30+
<string>___.___.___.___:27017</string>
31+
<string>--nickname</string>
32+
<string>YOUR-PROVIDER-NAME</string>
33+
<string>--log-level</string>
34+
<string>info</string>
35+
</array>
36+
<key>RunAtLoad</key>
37+
<true/>
38+
<key>KeepAlive</key>
39+
<true/>
40+
<key>StandardOutPath</key>
41+
<string>/var/log/gads-provider.log</string>
42+
<key>StandardErrorPath</key>
43+
<string>/var/log/gads-provider-err.log</string>
44+
<key>WorkingDirectory</key>
45+
<string>/Users/admin/gads</string>
46+
</dict>
47+
</plist>
48+
```
49+
50+
## Load the service
51+
To activate the service, you must set the correct system permissions and then bootstrap it into the system domain.
52+
53+
```bash
54+
# Set the correct ownership (root is required for LaunchDaemons)
55+
sudo chown root:wheel /Library/LaunchDaemons/com.gads.provider.plist
56+
57+
# Load and start the service
58+
sudo launchctl bootstrap system /Library/LaunchDaemons/com.gads.provider.plist
59+
```
60+
61+
## Manage the service
62+
You can monitor and control the provider using standard macOS launchctl commands.
63+
64+
## Check status
65+
To verify the service is running, look for a PID (Process ID) in the first column. A 0 in the second column indicates a clean run, while a non-zero number indicates the last exit code.
66+
67+
```bash
68+
sudo launchctl list | grep gads
69+
```
70+
71+
## View logs
72+
The provider outputs all activity to the logs defined in the .plist. This is the best way to troubleshoot device connection issues.
73+
74+
```bash
75+
# Follow the live log
76+
tail -f /var/log/gads-provider.log
77+
78+
# Check for startup errors
79+
tail -f /var/log/gads-provider-err.log
80+
```
81+
82+
## Stop or Restart the service
83+
To stop the provider from running in the background:
84+
```bash
85+
sudo launchctl bootout system /Library/LaunchDaemons/com.gads.provider.plist
86+
```
87+
88+
To apply changes made to the .plist file, run the bootout command above followed by the bootstrap command from the Load the service section.
89+
90+
## Troubleshooting
91+
Input/Output Error: If bootstrap fails with Error 5, it usually means the service is already loaded or the file has a syntax error. Try a full reboot of the Mac.
92+
Permission Denied: Ensure the binary has Full Disk Access and that you used sudo for all launchctl commands.
93+
Device Offline: If the provider is running but devices are offline, check the logs to ensure the provider can reach the Hub's MongoDB port (27017).

0 commit comments

Comments
 (0)