From 4424d07402445fc74c1afb1b441f4a8812335fe1 Mon Sep 17 00:00:00 2001 From: "Justin W. Flory" Date: Fri, 15 Feb 2019 18:46:18 -0500 Subject: [PATCH] docs: Add new page to explain how to deploy Teleirc This commit is part of issue #118. A new page is added specifically to explain how to deploy Teleirc. It consolidates the **Usage** section from `installation.rst` and all of the `using-docker.rst` page. This commit intends to make deployment options more clear and easy to understand. Some methods were removed, like the ArchLinux package. It is many updates behind on the bot, so I think it's better to recommend people to use directly from source where possible. --- docs/deploy-teleirc.rst | 95 +++++++++++++++++++++++++++++++++++++++++ docs/index.rst | 2 +- docs/using-docker.rst | 73 ------------------------------- 3 files changed, 96 insertions(+), 74 deletions(-) create mode 100644 docs/deploy-teleirc.rst delete mode 100644 docs/using-docker.rst diff --git a/docs/deploy-teleirc.rst b/docs/deploy-teleirc.rst new file mode 100644 index 00000000..385094b5 --- /dev/null +++ b/docs/deploy-teleirc.rst @@ -0,0 +1,95 @@ +##################### +How to deploy Teleirc +##################### + +There are several ways to deploy Teleirc persistently. +This page offers suggestions on possible deployment options. + + +******* +systemd +******* + +The **recommended deployment method** is with `systemd `_. +This method requires a basic understanding of systemd unit files. +Create a unique systemd service for each Teleirc instance. + +A `provided systemd service `_ file is available. +Add the systemd unit file to ``/usr/lib/systemd/system/`` to activate it. +Now, ``systemctl`` can be used to control your Teleirc instance. + +Note the provided file makes two assumptions: + +- Using a dedicated system user (e.g. ``teleirc``) +- Teleirc config files located at ``/usr/lib64/teleirc/`` (i.e. files inside Teleirc repository) + + +*** +pm2 +*** + +`pm2 `_ keeps NodeJS running in the background. +If you run an application and it crashes, pm2 restarts the process. +pm2 also restarts processes if the server reboots. +Read the `pm2 documentation `_ for more information. + +After pm2 is installed, run these commands to start Teleirc:: + + cd teleirc/ + pm2 start -n my-teleirc-bot teleirc.js + + +****** +Docker +****** + +Docker is another way to deploy Teleirc. +Dockerfiles and images are available in ``images/``. + +Which image do I choose? +======================== + +Node Alpine Linux and Fedora images are provided. + ++------------------------------------------------------------------------------+-----------------------+---------+ +| Image | File | Size | ++==============================================================================+=======================+=========+ +| `Node Alpine Linux `_ (``node:10-alpine``) | ``Dockerfile.alpine`` | 374 MB | ++------------------------------------------------------------------------------+-----------------------+---------+ +| `Fedora latest `_ | ``Dockerfile.fedora`` | 569 MB | ++------------------------------------------------------------------------------+-----------------------+---------+ + +This guide uses ``alpine``. +If you wish to use ``fedora``, replace ``alpine`` with ``fedora``. + +Building Docker image +===================== + +You may see errors running ``yarn``. +You can safely ignore them. +They are not fatal. + +.. code-block:: bash + + docker build . -f images/Dockerfile.alpine -t teleirc + docker run -d -u teleirc --name teleirc --restart always \ + -e TELEIRC_TOKEN="000000000:AAAAAAaAAa2AaAAaoAAAA-a_aaAAaAaaaAA" \ + -e IRC_CHANNEL="#channel" \ + -e IRC_BOT_NAME="teleirc" \ + -e IRC_BLACKLIST="CowSayBot,AnotherNickToIgnore" \ + -e TELEGRAM_CHAT_ID="-0000000000000" \ + teleirc + +Docker Compose +============== + +Optionally, you may use `docker-compose `_. +An `example compose file `_ is provided. + +Run these commands to use Docker Compose: + +.. code-block:: bash + + cp images/docker-compose.yml.example docker-compose.yml + cp env.example .env + docker-compose up -d teleirc diff --git a/docs/index.rst b/docs/index.rst index f2e744df..f208010f 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -14,7 +14,7 @@ Today, it is used by various communities. :caption: Contents installation - using-docker + deploy-teleirc config-file-glossary who-uses-teleirc diff --git a/docs/using-docker.rst b/docs/using-docker.rst deleted file mode 100644 index cbf62f00..00000000 --- a/docs/using-docker.rst +++ /dev/null @@ -1,73 +0,0 @@ -############ -Using Docker -############ - -Dockerfiles and images are available in ``images/`` for configuring and running Teleirc. -Install Docker onto the machine you plan to run Teleirc from. - - -************************ -Which image do I choose? -************************ - -Official Node Alpine Linux, and Fedora images are provided (ordered ascending by size). - -+-----------------------------------------------------------------------------+-----------------------+---------+ -| Image | File | Size | -+=============================================================================+=======================+=========+ -| `Node Alpine Linux `_ (``node:8-alpine``) | ``Dockerfile.alpine`` | 374 MB | -+-----------------------------------------------------------------------------+-----------------------+---------+ -| `Fedora latest `_ | ``Dockerfile.fedora`` | 569 MB | -+-----------------------------------------------------------------------------+-----------------------+---------+ - -This guide uses ``alpine``. -If you wish to use ``fedora``, replace ``alpine`` with ``fedora``. - -You will see errors during ``yarn``. -You can safely ignore them. -They are not fatal. - - -********************* -Building Docker image -********************* - -.. code-block:: bash - - docker build . -f images/Dockerfile.alpine -t teleirc - docker run -d -u teleirc --name teleirc --restart always \ - -e TELEIRC_TOKEN="000000000:AAAAAAaAAa2AaAAaoAAAA-a_aaAAaAaaaAA" \ - -e IRC_CHANNEL="#channel" \ - -e IRC_BOT_NAME="teleirc" \ - -e IRC_BLACKLIST="CowSayBot,AnotherNickToIgnore" \ - -e TELEGRAM_CHAT_ID="-0000000000000" \ - teleirc - - -************** -Docker Compose -************** - -Optionally, you may use `docker-compose `_. -We provide an example compose file (``images/docker-compose.yml``). - -.. code-block:: yaml - - version: '2' - services: - teleirc: - user: teleirc - build: - context: .. - dockerfile: images/Dockerfile.alpine - env_file: .env - -Running with Compose -==================== - -Run these commands to begin using Teleirc with Docker Compose. - - -#. Copy ``docker-compose.yml.example`` to ``docker-compose.yml`` and edit if you do not wish to use the alpine image -#. Copy ``.env.example`` to ``.env`` and edit accordingly. -#. ``docker-compose up -d teleirc``