From 610561d5070a22c12507bf10a49dbd0d79e779a5 Mon Sep 17 00:00:00 2001 From: octodog Date: Thu, 28 Nov 2024 20:16:29 +0900 Subject: [PATCH] docs: Updated package-based installation documentation for version 24.03.6 (#2664) (#3169) Co-authored-by: Sion Kang Co-authored-by: Joongi Kim --- .readthedocs.yaml | 9 ++ docs/install/install-from-package.rst | 1 + .../install-from-package/install-agent.rst | 3 +- .../install-from-package/install-manager.rst | 4 +- .../install-webserver.rst | 6 +- .../install-from-package/install-wsproxy.rst | 146 ++++++++++++++++++ .../prepare-cache-service.rst | 1 + .../prepare-config-service.rst | 1 + .../install-from-package/prepare-database.rst | 3 +- 9 files changed, 166 insertions(+), 8 deletions(-) create mode 100644 docs/install/install-from-package/install-wsproxy.rst diff --git a/.readthedocs.yaml b/.readthedocs.yaml index 6ca9a66dda9..455b4d99225 100644 --- a/.readthedocs.yaml +++ b/.readthedocs.yaml @@ -18,6 +18,15 @@ build: pre_build: # Auto-generate REST API reference - PYTHONPATH="src" python -m ai.backend.manager.openapi -o docs/manager/rest-reference/openapi.json + - | + if [ "$READTHEDOCS_VERSION_TYPE" != "external" ]; + then + mkdir docs/fonts + curl -L https://github.com/orioncactus/pretendard/releases/download/v1.3.9/Pretendard-1.3.9.zip -o pretendard.zip + unzip -o pretendard.zip -d docs/fonts/Pretendard + curl -L https://github.com/naver/d2codingfont/releases/download/VER1.3.2/D2Coding-Ver1.3.2-20180524.zip -o d2coding.zip + unzip -o d2coding.zip -d docs/fonts/D2Coding + fi python: install: - requirements: requirements.txt diff --git a/docs/install/install-from-package.rst b/docs/install/install-from-package.rst index 1b139337e55..31465d53121 100644 --- a/docs/install/install-from-package.rst +++ b/docs/install/install-from-package.rst @@ -52,3 +52,4 @@ more management nodes, although this is not the focus of this guide. install-from-package/install-agent install-from-package/install-storage-proxy install-from-package/install-webserver + install-from-package/install-wsproxy diff --git a/docs/install/install-from-package/install-agent.rst b/docs/install/install-from-package/install-agent.rst index 1062c9aa702..31e8c3db569 100644 --- a/docs/install/install-from-package/install-agent.rst +++ b/docs/install/install-from-package/install-agent.rst @@ -77,8 +77,7 @@ would be: port-range = [30000, 31000] kernel-uid = 1100 kernel-gid = 1100 - bind-host = "bai-m1" - advertised-host = "bai-m1" + bind-host = "127.0.0.1" stats-type = "docker" sandbox-type = "docker" jail-args = [] diff --git a/docs/install/install-from-package/install-manager.rst b/docs/install/install-from-package/install-manager.rst index 014f8905b28..21152f48d87 100644 --- a/docs/install/install-from-package/install-manager.rst +++ b/docs/install/install-from-package/install-manager.rst @@ -156,7 +156,7 @@ Also, populate the Storage Proxy configuration to the Etcd: $ # Set the "bai-m1" proxy information. $ # User (browser) facing API endpoint of Storage Proxy. $ # Cannot use host alias here. It should be user-accessible URL. - $ backend.ai mgr etcd put volumes/proxies/bai-m1/client_api "http://10.20.30.10:6021" + $ backend.ai mgr etcd put volumes/proxies/bai-m1/client_api "http://127.0.0.1:6021" $ # Manager facing internal API endpoint of Storage Proxy. $ backend.ai mgr etcd put volumes/proxies/bai-m1/manager_api "http://bai-m1:6022" $ # Random secret string which is used by Manager to communicate with Storage Proxy. @@ -208,8 +208,10 @@ your initial superadmin and sample user accounts for security. .. code-block:: console $ backend.ai mgr schema oneshot + $ backend.ai mgr fixture populate ./users.json $ backend.ai mgr fixture populate ./keypairs.json $ backend.ai mgr fixture populate ./resource-presets.json + $ backend.ai mgr fixture populate ./set-user-main-access-keys.json Sync the information of container registry diff --git a/docs/install/install-from-package/install-webserver.rst b/docs/install/install-from-package/install-webserver.rst index 408501af840..b65560627fd 100644 --- a/docs/install/install-from-package/install-webserver.rst +++ b/docs/install/install-from-package/install-webserver.rst @@ -34,8 +34,7 @@ would be: [service] ip = "0.0.0.0" port = 8080 - # Not active in open-source edition. - wsproxy.url = "http://10.20.30.10:10200" + wsproxy.url = {url = "http://127.0.0.1:5050"} # Set or enable it when using reverse proxy for SSL-termination # force_endpoint_protocol = "https" @@ -77,8 +76,7 @@ would be: ssl-verify = false [session] - redis.host = "bai-m1" - redis.port = 8110 + redis.addr = "bai-m1:8110" redis.db = 5 redis.password = "develove" max_age = 604800 # 1 week diff --git a/docs/install/install-from-package/install-wsproxy.rst b/docs/install/install-from-package/install-wsproxy.rst new file mode 100644 index 00000000000..6a492590208 --- /dev/null +++ b/docs/install/install-from-package/install-wsproxy.rst @@ -0,0 +1,146 @@ +Install Backend.AI WSProxy +========================= + +Refer to :ref:`prepare_python_and_venv` to setup Python and virtual environment +for the service. + +Install the latest version of Backend.AI WSProxy for the current Python +version: + +.. code-block:: console + + $ cd "${HOME}/wsproxy" + $ # Activate a virtual environment if needed. + $ pip install -U backend.ai-wsproxy + +If you want to install a specific version: + +.. code-block:: console + + $ pip install -U backend.ai-wsproxy==${BACKEND_PKG_VERSION} + + +Local configuration +------------------- + +Backend.AI WSProxy uses a config file (``wsproxy.conf``) to configure +local service. Refer to the +`wsproxy.conf sample file `_ +for a detailed description of each section and item. A configuration example +would be: + +.. code-block:: toml + + [wsproxy] + bind_host = "127.0.0.1" + advertised_host = "127.0.0.1" + + bind_api_port = 5050 + advertised_api_port = 5050 + + # replace these values with your passphrase + jwt_encrypt_key = "50M3G00DL00KING53CR3T" + permit_hash_key = "50M3G00DL00KING53CR3T" + api_secret = "v625xZLOgbMHhl0s49VuqQ" + + +Save the contents to ``${HOME}/.config/backend.ai/wsproxy.toml``. + +Run Backend.AI WSProxy service +------------------------------ + +You can run the service by specifying the config file path with ``-f`` option: + +.. code-block:: console + + $ cd "${HOME}/wsproxy" + $ python -m ai.backend.wsproxy.server -f ${HOME}/.config/backend.ai/wsproxy.toml + +Press ``Ctrl+C`` to stop both services. + + +Register systemd service +------------------------ + +The service can be registered as a systemd daemon. It is recommended to +automatically run the service after rebooting the host machine, although this is +entirely optional. + +First, create a runner script at ``${HOME}/bin/run-wsproxy.sh``: + +.. code-block:: bash + + #! /bin/bash + set -e + + if [ -z "$HOME" ]; then + export HOME="/home/bai" + fi + + # -- If you have installed using static python -- + source .venv/bin/activate + + # -- If you have installed using pyenv -- + if [ -z "$PYENV_ROOT" ]; then + export PYENV_ROOT="$HOME/.pyenv" + export PATH="$PYENV_ROOT/bin:$PATH" + fi + eval "$(pyenv init --path)" + eval "$(pyenv virtualenv-init -)" + + if [ "$#" -eq 0 ]; then + exec python -m ai.backend.wsproxy.server -f ${HOME}/.config/backend.ai/wsproxy.toml + else + exec "$@" + fi + +Make the scripts executable: + +.. code-block:: console + + $ chmod +x "${HOME}/bin/run-wsproxy.sh" + +Then, create a systemd service file at +``/etc/systemd/system/backendai-wsproxy.service``: + +.. code-block:: dosini + + [Unit] + Description= Backend.AI WSProxy + Requires=network.target + After=network.target remote-fs.target + + [Service] + Type=simple + ExecStart=/home/bai/bin/run-wsproxy.sh + PIDFile=/home/bai/wsproxy/wsproxy.pid + WorkingDirectory=/home/bai/wsproxy + User=1100 + Group=1100 + TimeoutStopSec=5 + KillMode=process + KillSignal=SIGTERM + PrivateTmp=false + Restart=on-failure + RestartSec=10 + LimitNOFILE=5242880 + LimitNPROC=131072 + + [Install] + WantedBy=multi-user.target + +Finally, enable and start the service: + +.. code-block:: console + + $ sudo systemctl daemon-reload + $ sudo systemctl enable --now backendai-wsproxy + + $ # To check the service status + $ sudo systemctl status backendai-wsproxy + $ # To restart the service + $ sudo systemctl restart backendai-wsproxy + $ # To stop the service + $ sudo systemctl stop backendai-wsproxy + $ # To check the service log and follow + $ sudo journalctl --output cat -u backendai-wsproxy -f diff --git a/docs/install/install-from-package/prepare-cache-service.rst b/docs/install/install-from-package/prepare-cache-service.rst index 5284bfdc05a..b48cca9b9a1 100644 --- a/docs/install/install-from-package/prepare-cache-service.rst +++ b/docs/install/install-from-package/prepare-cache-service.rst @@ -22,6 +22,7 @@ refer services: backendai-halfstack-redis: <<: *base + container_name: backendai-halfstack-redis image: redis:6.2-alpine restart: unless-stopped command: > diff --git a/docs/install/install-from-package/prepare-config-service.rst b/docs/install/install-from-package/prepare-config-service.rst index 4dee7a07d6b..28033febdae 100644 --- a/docs/install/install-from-package/prepare-config-service.rst +++ b/docs/install/install-from-package/prepare-config-service.rst @@ -22,6 +22,7 @@ refer services: backendai-halfstack-etcd: <<: *base + container_name: backendai-halfstack-etcd image: quay.io/coreos/etcd:v3.4.15 restart: unless-stopped command: > diff --git a/docs/install/install-from-package/prepare-database.rst b/docs/install/install-from-package/prepare-database.rst index 2d4d6afbfbd..c2bf39c8342 100644 --- a/docs/install/install-from-package/prepare-database.rst +++ b/docs/install/install-from-package/prepare-database.rst @@ -22,7 +22,8 @@ refer services: backendai-pg-active: <<: *base - image: postgres:15.1-alpine + image: postgres:16.3-alpine + container_name: backendai-halfstack-db restart: unless-stopped command: > postgres