From 9e37e2fa40fb07bb878e0f3e69c3a68eec67ea05 Mon Sep 17 00:00:00 2001
From: Johnshall <71166067+Johnshall@users.noreply.github.com>
Date: Tue, 30 Aug 2022 12:49:10 +0800
Subject: [PATCH] Add documents to install on MacOS

---
 docs/examples/index.md                 |  1 +
 docs/examples/macos-installation.md    | 61 ++++++++++++++++++++++++++
 docs/examples/macos-installation.zh.md | 61 ++++++++++++++++++++++++++
 mkdocs.yml                             |  2 +
 4 files changed, 125 insertions(+)
 create mode 100644 docs/examples/macos-installation.md
 create mode 100644 docs/examples/macos-installation.zh.md

diff --git a/docs/examples/index.md b/docs/examples/index.md
index 49b0e81f..a8877ead 100644
--- a/docs/examples/index.md
+++ b/docs/examples/index.md
@@ -3,6 +3,7 @@
 Configuration examples for sing-box.
 
 * [Linux Server Installation](./linux-server-installation)
+* [MacOS Installation](./macos-installation.md)
 * [Shadowsocks Server](./ss-server)
 * [Shadowsocks Client](./ss-client)
 * [Shadowsocks Tun](./ss-tun)
diff --git a/docs/examples/macos-installation.md b/docs/examples/macos-installation.md
new file mode 100644
index 00000000..a36ea933
--- /dev/null
+++ b/docs/examples/macos-installation.md
@@ -0,0 +1,61 @@
+#### Download sing-box
+
+Download sing-box macOS binary package from [GitHub Releases](https://github.com/SagerNet/sing-box/releases/latest) or Github Actions. Move the `sing-box` to the appropriate location (e.g. /Applications/sing-box/, hereafter referred to as the `working directory`).
+
+#### Creates Plist file
+
+Create a new Plist file and save to ~/Library/LaunchAgents/
+
+Example:
+
+```bash
+nano ~/Library/LaunchAgents/org.sagernet.sing-box.plist
+```
+
+The content is as follows (`[]` needs to be deleted) :
+
+```xml
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+    <key>KeepAlive</key>
+    <true/>
+    <key>Label</key>
+    <string>org.sagernet.sing-box</string>
+    <key>ProgramArguments</key>
+    <array>
+        <string>/Applications/sing-box/sing-box [Path to sing-box]</string>
+        <string>run</string>
+        <string>--config</string>
+        <string>/Applications/sing-box/config.json [Path to config.json]</string>
+        <string>--directory</string>
+        <string>/Applications/sing-box [Path to working directory]</string>
+    </array>
+    <key>RunAtLoad</key>
+    <true/>
+</dict>
+</plist>
+```
+
+#### Check the Plist file
+
+```bash
+plutil ~/Library/LaunchAgents/org.sagernet.sing-box.plist
+```
+
+#### Load the plist file
+
+```bash
+launchctl load ~/Library/LaunchAgents/org.sagernet.sing-box.plist
+```
+
+#### Confirm
+
+```bash
+launchctl list | grep org.sagernet.sing-box
+```
+
+After the correct configuration, sing-box will be load after booting automatically.
+
+To stop the Sing-box service, replace the command from `load` to `unload`.
diff --git a/docs/examples/macos-installation.zh.md b/docs/examples/macos-installation.zh.md
new file mode 100644
index 00000000..029e4b76
--- /dev/null
+++ b/docs/examples/macos-installation.zh.md
@@ -0,0 +1,61 @@
+#### 下载 sing-box
+
+从 [GitHub Releases](https://github.com/SagerNet/sing-box/releases/latest) 或 GitHub Actions 下载适用于 macOS 的压缩包，解压后将 `sing-box` 文件复制到合适的位置（例如：`/Applications/sing-box/`，后文简称为`工作目录`）。
+
+#### 建立服务文件
+
+新建服务文件并保存到 ~/Library/LaunchAgents/
+
+示例：
+
+```bash
+nano ~/Library/LaunchAgents/org.sagernet.sing-box.plist
+```
+
+内容如下（`【】`需要删除）：
+
+```xml
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+    <key>KeepAlive</key>
+    <true/>
+    <key>Label</key>
+    <string>org.sagernet.sing-box</string>
+    <key>ProgramArguments</key>
+    <array>
+        <string>/Applications/sing-box/sing-box【可执行文件路径】</string>
+        <string>run</string>
+        <string>--config</string>
+        <string>/Applications/sing-box/config.json【配置文件路径】</string>
+        <string>--directory</string>
+        <string>/Applications/sing-box【工作目录】</string>
+    </array>
+    <key>RunAtLoad</key>
+    <true/>
+</dict>
+</plist>
+```
+
+#### 检查文件是否正确
+
+```bash
+plutil ~/Library/LaunchAgents/org.sagernet.sing-box.plist
+```
+
+#### 加载plist文件
+
+```bash
+launchctl load ~/Library/LaunchAgents/org.sagernet.sing-box.plist
+```
+
+#### 确认加载
+
+```bash
+launchctl list | grep org.sagernet.sing-box
+```
+
+正确配置后 sing-box 将开机自启动。
+
+如果需要关闭 sing-box 服务，将上述命令从 `load` 替换为 `unload` 即可。
diff --git a/mkdocs.yml b/mkdocs.yml
index f51b298d..f14b5b49 100644
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -90,6 +90,7 @@ nav:
   - Examples:
       - examples/index.md
       - Linux Server Installation: examples/linux-server-installation.md
+      - MacOS Installation: examples/macos-installation.md
       - Shadowsocks Server: examples/ss-server.md
       - Shadowsocks Client: examples/ss-client.md
       - Shadowsocks Tun: examples/ss-tun.md
@@ -158,6 +159,7 @@ plugins:
           Known Issues: 已知问题
           Examples: 示例
           Linux Server Installation: Linux 服务器安装
+          MacOS Installation: MacOS 安装
           Shadowsocks Server: Shadowsocks 服务器
           Shadowsocks Client: Shadowsocks 客户端
           Shadowsocks Tun: Shadowsocks Tun