Skip to content

Commit

Permalink
✒️ docs: Reflect initial v2.x.x changes (closes #278) (#279)
Browse files Browse the repository at this point in the history 
This commit makes a quick pass through all of our documentation to make
sure we clearly distinguish the project as a Go project, and not a Node
project. Some admonitions (i.e. `seealso::`, `note::`, `warning::`,
etc.) were added to mark some pages as works-in-progress, like our
deployment docs.

The contributor guidelines were also updated with basic guidance on how
to set up a developer environment for the Go project. Future docs PRs
will work on improving the things we have based on the v2.x.x changes.

Closes #278.

Signed-off-by: Justin W. Flory <git@jwf.io>

Co-authored-by: Tim Zabel <Tjzabel21@gmail.com>
Co-authored-by: kennedy <854543+kennedy@users.noreply.github.com>
  • Loading branch information
@jwflory @Tjzabel @kennedy
3 people committed Mar 29, 2020
1 parent c56cd65 commit dc3e3c4
Show file tree
Hide file tree
Showing 7 changed files with 134 additions and 152 deletions.
73 changes: 48 additions & 25 deletions docs/about/who-uses-teleirc.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,53 +2,76 @@
Who uses TeleIRC?
#################

The following list of projects and communities use RITlug TeleIRC:
******
v2.x.x
******

The following projects and communities use RITlug TeleIRC v2.0.0 or later:

- None yet.
Check back later!

******
v1.x.x
******

The following projects and communities use a v1.x.x release of RITlug TeleIRC:

- `BSD Argentina <http://sysarmy.com/bsdar>`_ (`@bsdar <https://t.me/bsdar>`_ | `#bsdar <https://webchat.freenode.net/?channels=bsdar>`_)

- `CityZen app <https://cityzenapp.co>`_ (`@CityZenApp <https://t.me/CityZenApp>`_ | `#cityzen <https://webchat.freenode.net/?channels=cityzen>`_)
- `CityZen app <https://cityzenapp.co>`_ (`@CityZenApp <https://t.me/CityZenApp>`_ | `#cityzen <https://webchat.freenode.net/?channels=cityzen>`_)

- `Fedora Project <https://docs.fedoraproject.org/en-US/project/>`_ (`@fedora <https://t.me/fedora>`_ | `#fedora-telegram <https://webchat.freenode.net/?channels=fedora-telegram>`_)

- `Fedora Albania <https://www.facebook.com/fedorasq/>`_ (`@FedoraAlbania <https://t.me/FedoraAlbania>`_ | `#fedora-sq <https://webchat.freenode.net/?channels=fedora-sq>`_)

- `Fedora CommOps <https://docs.fedoraproject.org/en-US/commops/>`_ (`@fedoracommops <https://t.me/fedoracommops>`_ | `#fedora-commops <https://webchat.freenode.net/?channels=fedora-commops>`_ )

- `Fedora Diversity and Inclusion Team <https://docs.fedoraproject.org/en-US/diversity-inclusion/team/>`_ (`@fedoradiversity <https://t.me/fedoradiversity>`_ | `#fedora-diversity <https://webchat.freenode.net/?channels=fedora-diversity>`_ )

- `Fedora Project <https://docs.fedoraproject.org/en-US/project/>`_ (`@fedora <https://t.me/fedora>`_ | `#fedora-telegram <https://webchat.freenode.net/?channels=fedora-telegram>`_)
- `Fedora Albania <https://www.facebook.com/fedorasq/>`_ (`@FedoraAlbania <https://t.me/FedoraAlbania>`_ | `#fedora-sq <https://webchat.freenode.net/?channels=fedora-sq>`_)
- `Fedora CommOps <https://docs.fedoraproject.org/en-US/commops/>`_ (`@fedoracommops <https://t.me/fedoracommops>`_ | `#fedora-commops <https://webchat.freenode.net/?channels=fedora-commops>`_ )
- `Fedora Diversity and Inclusion Team <https://docs.fedoraproject.org/en-US/diversity-inclusion/team/>`_ (`@fedoradiversity <https://t.me/fedoradiversity>`_ | `#fedora-diversity <https://webchat.freenode.net/?channels=fedora-diversity>`_ )
- `Fedora LATAM <http://fedoracommunity.org/latam>`__ (`@fedoralat <https://t.me/fedoralat>`__ | `#fedora-latam <https://webchat.freenode.net/?channels=fedora-latam>`__)
- `Fedora Marketing Team <https://fedoraproject.org/wiki/Marketing>`_ (`@fedoramktg <https://t.me/fedoramktg>`_ | `#fedora-mktg <https://webchat.freenode.net/?channels=fedora-mktg>`_ )
- `Flock to Fedora <https://flocktofedora.org>`_ (`@flocktofedora <https://t.me/flocktofedora>`_ | `#fedora-flock <https://webchat.freenode.net/?channels=fedora-flock>`_)
- `Fedora LATAM <http://fedoracommunity.org/latam>`__ (`@fedoralat <https://t.me/fedoralat>`__ | `#fedora-latam <https://webchat.freenode.net/?channels=fedora-latam>`__)

- `FOSS@MAGIC at RIT <http://foss.rit.edu>`_ (`@fossrit <https://t.me/fossrit>`_ | `#rit-foss <https://webchat.freenode.net/?channels=rit-foss>`_)
- `Fedora Marketing Team <https://fedoraproject.org/wiki/Marketing>`_ (`@fedoramktg <https://t.me/fedoramktg>`_ | `#fedora-mktg <https://webchat.freenode.net/?channels=fedora-mktg>`_ )

- `Hamara Linux <https://hamaralinux.org>`_ (`@hamaraLinux
<https://t.me/hamaraLinux>`_ | `#hamara <https://webchat.oftc.net/?channels=#hamara>`_)
- `Flock to Fedora <https://flocktofedora.org>`_ (`@flocktofedora <https://t.me/flocktofedora>`_ | `#fedora-flock <https://webchat.freenode.net/?channels=fedora-flock>`_)

- `LibreOffice Community <https://www.libreoffice.org/>`_ (`@libreofficecommunity <https://t.me/libreofficecommunity>`_ | `#libreoffice-telegram <https://webchat.freenode.net/?channels=libreoffice-telegram>`_)
- `LibreLadies <https://www.mail-archive.com/libreladies@documentfoundation.org/info.html>`_ (*Telegram invite-only* | `#libreladies <https://webchat.freenode.net/?channels=libreladies>`_)
- `LibreOffice AppImage <https://appimage.org/>`_ (*no public invite link* | `#libreoffice-appimage <https://webchat.freenode.net/?channels=libreoffice-appimage>`_)
- `LibreOffice Design Team <https://wiki.documentfoundation.org/Design>`_ (*no public invite link* | `#libreoffice-design <https://webchat.freenode.net/?channels=libreoffice-design>`_)
- `LibreOffice QA Team <https://www.libreoffice.org/community/qa/>`_ (*no public invite link* | `#libreoffice-qa <https://webchat.freenode.net/?channels=libreoffice-qa>`_)
- `FOSS@MAGIC at RIT <http://foss.rit.edu>`_ (`@fossrit <https://t.me/fossrit>`_ | `#rit-foss <https://webchat.freenode.net/?channels=rit-foss>`_)

- `Hamara Linux <https://hamaralinux.org>`_ (`@hamaraLinux <https://t.me/hamaraLinux>`_ | `#hamara <https://webchat.oftc.net/?channels=#hamara>`_)

- `LibreOffice Community <https://www.libreoffice.org/>`_ (`@libreofficecommunity <https://t.me/libreofficecommunity>`_ | `#libreoffice-telegram <https://webchat.freenode.net/?channels=libreoffice-telegram>`_)

- `LibreLadies <https://www.mail-archive.com/libreladies@documentfoundation.org/info.html>`_ (*Telegram invite-only* | `#libreladies <https://webchat.freenode.net/?channels=libreladies>`_)

- `LibreOffice AppImage <https://appimage.org/>`_ (*no public invite link* | `#libreoffice-appimage <https://webchat.freenode.net/?channels=libreoffice-appimage>`_)

- `LibreOffice Design Team <https://wiki.documentfoundation.org/Design>`_ (*no public invite link* | `#libreoffice-design <https://webchat.freenode.net/?channels=libreoffice-design>`_)

- `LibreOffice QA Team <https://www.libreoffice.org/community/qa/>`_ (*no public invite link* | `#libreoffice-qa <https://webchat.freenode.net/?channels=libreoffice-qa>`_)

- `Linux Users Massa Carrara <https://www.lumacaonline.org/>`_ (`Telegram <https://t.me/joinchat/Afu_TAczLfB4dQRKeYQCqg>`_ | `IRC <https://www.lumacaonline.org/webchat.php>`_)

- `MINECON Agents <https://mojang.com/2016/06/calling-all-agents-help-us-run-minecon-2016/>`_ (*no public invite link* | `#MineconAgents <https://webchat.esper.net/?channels=MineconAgents>`_)
- `MINECON Agents <https://mojang.com/2016/06/calling-all-agents-help-us-run-minecon-2016/>`_ (*no public invite link* | `#MineconAgents <https://webchat.esper.net/?channels=MineconAgents>`_)

- `MusicBrainz <https://musicbrainz.org/doc/About>`_ (`@musicbrainz <https://t.me/musicbrainz>`_ | `#musicbrainz-telegram <https://webchat.freenode.net/?channels=musicbrainz-telegram>`_)

- `MusicBrainz <https://musicbrainz.org/doc/About>`_ (`@musicbrainz <https://t.me/musicbrainz>`_ | `#musicbrainz-telegram <https://webchat.freenode.net/?channels=musicbrainz-telegram>`_)
- `Pure Data <https://puredata.info/>`_ (`@puredata <https://t.me/puredata>`_ | `#dataflow <https://webchat.freenode.net/?channels=dataflow>`_)

- `Pure Data <https://puredata.info/>`_ (`@puredata <https://t.me/puredata>`_ | `#dataflow <https://webchat.freenode.net/?channels=dataflow>`_)
- `RITlug <https://ritlug.com>`_ (`@ritlug <https://t.me/ritlug>`_ | `#rit-lug <https://webchat.freenode.net/?channels=rit-lug>`_)

- `RITlug <https://ritlug.com>`_ (`@ritlug <https://t.me/ritlug>`_ | `#rit-lug <https://webchat.freenode.net/?channels=rit-lug>`_)
- `RITlug teleirc <https://github.com/RITlug/teleirc>`_ (`@teleirc <https://t.me/teleirc>`_ | `#rit-lug-teleirc <https://webchat.freenode.net/?channels=rit-lug-teleirc>`_)
- `RITlug teleirc <https://github.com/RITlug/teleirc>`_ (`@teleirc <https://t.me/teleirc>`_ | `#rit-lug-teleirc <https://webchat.freenode.net/?channels=rit-lug-teleirc>`_)


***********************
How to get on this list
***********************

Want to have your community added to this page?
Let us know you're using TeleIRC too!
`Submit an issue <https://github.com/RITlug/teleirc/issues/new>`_ against this repo with the following info:
Let us know you are using TeleIRC too!
`Open an issue <https://github.com/RITlug/teleirc/issues/new>`_ with the following info:

- Organization / group name and website
- Telegram group URL
- Your IRC channel

To be added, your group must not discuss illegal, illicit, or generally inappropriate content.
To be added, your group must not discuss illegal, illicit, or sexually explicit content.
29 changes: 11 additions & 18 deletions docs/config-file-glossary.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,7 @@ Config file glossary
####################

This page is a glossary of different settings in the ``env.example`` configuration file.
The values shown for the settings are their defaults.
All values shown are the default settings.
This glossary is intended for advanced users.


Expand All @@ -17,11 +17,11 @@ IRC settings
``IRC_BOT_NAME=teleirc``
IRC nickname for bot

``IRC_CHANNEL=#channel``
``IRC_CHANNEL="#channel"``
IRC channel for bot to join

``IRC_CHANNEL_KEY=""``
IRC channel key
IRC channel key, for password-protected channels

``IRC_SEND_STICKER_EMOJI=true``
Send emojis associated with a sticker to IRC (when a Telegram user sends a sticker)
Expand All @@ -45,10 +45,10 @@ IRC settings
IRC server port

``IRC_CERT_ALLOW_SELFSIGNED=false``
Allows SSL to accept SSL certificates from non-trusted CA
Allows TeleIRC to accept TLS/SSL certificates from non-trusted/unknown Certificate Authorities (CA)

``IRC_CERT_ALLOW_EXPIRED=false``
Allow connecting to IRC server with SSL expired cert
Allow connecting to IRC server with an expired TLS/SSL certificate

``IRC_NICKSERV_SERVICE=NickServ``
IRC service used for authentication
Expand All @@ -57,11 +57,11 @@ IRC settings
IRC account password to complete IRC authentication

``IRC_EDITED_PREFIX="[EDIT] "``
Prefix to include when a user edits a Telegram message and it is resent to IRC
Prefix to prepend to messages when a user edits a Telegram message and it is resent to IRC

``IRC_MAX_MESSAGE_LENGTH=400``
Maximum length of the message that can be sent to IRC.
Longer messages will be split into multiple messages.
Longer messages are split into multiple messages.


*****************
Expand Down Expand Up @@ -97,14 +97,7 @@ Imgur settings
``USE_IMGUR_FOR_IMAGES=true``
Upload picture messages from Telegram to Imgur, send Imgur link to IRC

``IMGUR_CLIENT_ID=0000000000``
Imgur API client ID value to access Imgur API


**********************
Miscellaneous settings
**********************

``NTBA_FIX_319=1``
Required to fix a bug in a library used by TeleIRC.
For context, see `yagop/node-telegram-bot-api#319 <https://github.com/yagop/node-telegram-bot-api/issues/319#issuecomment-324963294>`_.
``IMGUR_CLIENT_ID=7d6b00b87043f58``
Imgur API client ID value to access Imgur API.
Uses a default API key.
If you are bridging to a very active Telegram group, *please register your own API key*.
88 changes: 39 additions & 49 deletions docs/deploy-teleirc.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,58 +2,62 @@
How to deploy TeleIRC
#####################

There are several ways to deploy TeleIRC persistently.
This page offers suggestions on possible deployment options.
.. warning:: This page is not yet fully updated for TeleIRC v2.0.0 or later.
It is a work-in-progress.
When the instructions here are "production-ready," this warning will be removed.
Follow `RITlug/teleirc#193 <https://github.com/RITlug/teleirc/issues/193>`_ and `RITlug/teleirc#228 <https://github.com/RITlug/teleirc/issues/228>`_ to track progress.

There are two ways to deploy TeleIRC persistently:

*******
systemd
*******
#. Run Go binary
#. Run TeleIRC in a container

The **recommended deployment method** is with `systemd <https://en.wikipedia.org/wiki/Systemd>`_.
This method requires a basic understanding of systemd unit files.
Create a unique systemd service for each TeleIRC instance.

A `provided systemd service <https://github.com/RITlug/teleirc/blob/master/misc/teleirc.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.
*************
Run Go binary
*************

Note the provided file makes two assumptions:
This section explains how to configure and install TeleIRC as a simple executable binary.

- Using a dedicated system user (e.g. ``teleirc``)
- TeleIRC config files located at ``/usr/lib64/teleirc/`` (i.e. files inside TeleIRC repository)
Requirements
============

- git
- go (v1.13.x or later)

***
pm2
***
Install dependencies
====================

`pm2 <http://pm2.keymetrics.io/>`_ 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 <http://pm2.keymetrics.io/docs/usage/quick-start/>`_ for more information.
#. Clone the repository (``git clone https://github.com/RITlug/teleirc.git``)
#. Install dependencies (``go install``)

After pm2 is installed, run these commands to start TeleIRC::
Configuration
=============

cd teleirc/
pm2 start -n my-teleirc-bot teleirc.js
TeleIRC uses `godotenv <https://github.com/joho/godotenv>`_ to manage API keys and settings.
The config file is a ``.env`` file.
Copy the example file to a production file to get started (``cp env.example .env``).
Edit the ``.env`` file with your API keys and settings.

.. seealso::

**************
Arch Linux AUR
**************
See :doc:`config-file-glossary` for detailed information.

On ArchLinux, see `teleirc-git <https://aur.archlinux.org/packages/teleirc-git/>`_ in the AUR.
The AUR package uses the systemd method to deploy TeleIRC.
Place TeleIRC configuration files in the ``/usr/lib/teleirc/`` directory.
Start bot
=========

.. note:: Work in progress.

******
Docker
******

Docker is another way to deploy TeleIRC.
Dockerfiles and images are available in ``images/``.
***************
Run a container
***************

Containers are another way to deploy TeleIRC.
Dockerfiles and other deployment resources are available in ``deployments/``.

.. important:: The below instructions only apply to v1.x.x releases.
Once a v2.x.x container image is created, these instructions will change.

Which image do I choose?
========================
Expand Down Expand Up @@ -88,17 +92,3 @@ They are not fatal.
-e IRC_BLACKLIST="CowSayBot,AnotherNickToIgnore" \
-e TELEGRAM_CHAT_ID="-0000000000000" \
teleirc
Docker Compose
==============

Optionally, you may use `docker-compose <https://docs.docker.com/compose>`_.
An `example compose file <https://github.com/RITlug/teleirc/blob/master/images/docker-compose.yml.example>`_ 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
36 changes: 18 additions & 18 deletions docs/dev/contributing.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -7,8 +7,8 @@ Contributing guidelines
-->

This guide explains how to contribute to the TeleIRC project.
It explicitly defines working practices of the development team.
This document helps new contributors get up to speed with working on the project.
It defines working practices of the development team.
This document helps new contributors start working on the project.
It is a living document and will change.
If you think something could be better, please [open an issue](https://github.com/RITlug/teleirc/issues/new/choose) with your feedback.

Expand All @@ -33,15 +33,15 @@ If you think something could be better, please [open an issue](https://github.co

To set up a TeleIRC development environment, you need the following:

* [Nodejs](https://nodejs.org/en/) (v10+ preferred)
* [Go](https://golang.org/dl/) (v1.13.x or later)
* Telegram account
* IRC client ([HexChat](https://hexchat.github.io/) recommended)
* For docs: [Python 3](https://www.python.org/downloads/) (3.6+ preferred)
* For docs: [Python 3](https://www.python.org/downloads/) (3.6 or later)

### Create Telegram bot

Create a Telegram bot using the Telegram [BotFather](https://t.me/botfather).
See [TeleIRC documentation](/quick-install) for more instructions on how to do this.
See the [TeleIRC Quick Install](/quick-install) for more instructions on how to do this.

### Create Telegram group

Expand All @@ -52,36 +52,36 @@ Configure the Telegram bot to TeleIRC specifications before adding it to the gro
### Register IRC channel

Registering an IRC channel is encouraged, but optional.
At the least, you need an unused IRC channel to use for testing.
At minimum, you need an unused IRC channel to use for testing.
Registering the channel gives you additional privileges as a channel operator (e.g. testing NickServ authentication to join private IRC channels).
See your IRC network's documentation on registering a channel.

### Configure and run TeleIRC

Change the `env.example` file to `.env`.
Change the configuration values to the Telegram bot's tokens.
For more help with configuration, see the [TeleIRC documentation](/quick-install).
For more help with configuration, see the [TeleIRC Quick Install](/quick-install).


## Open a new pull request
## Open a pull request

These guidelines help maintainers review new pull requests.
Stick to the guidelines for quicker and easier pull request reviews.

1. Prefer gradual small changes than sudden big changes
2. Write a helpful title for your pull request (if someone reads only one sentence, will they understand your change?)
3. Address the following questions in your pull request:
1. What is a summary of your change?
2. Why is this change helpful?
3. Any specific details to consider?
4. What do you think is the outcome of this change?
1. We prefer gradual, small changes over sudden, big changes
1. Write a helpful title for your pull request (if someone reads only one sentence, will they understand your change?)
1. Address the following questions in your pull request:
1. What is a short summary of your change?
1. Why is this change helpful?
1. Any specific details to consider?
1. What is the desired outcome of your change?


## Maintainer response time

Project maintainers are committed to **no more than 10 days for a reply** to a new ticket.
Current maintainers are volunteers working on the project, so we try to keep up with the project as best we can.
Project maintainers make a best effort to respond in **10 days or less** to new issues.
Current maintainers are volunteers working on the project, so we try to keep up as best we can.
If more than 10 days passed and you have not received a reply, follow up in [Telegram](https://t.me/teleirc) or [IRC](https://webchat.freenode.net/?channels=rit-lug-teleirc) (`#rit-lug-teleirc` on irc.freenode.net).
Someone may have missed your comment – we are not intentionally ignoring anyone.

_Remember_, using issue templates and answering the above questions in new pull requests likely reduces response time from a maintainer to your ticket / PR.
_Remember_, using issue templates and answering the above questions in new pull requests reduces the response time from a maintainer to your issue or pull request.
Loading

0 comments on commit dc3e3c4

Please sign in to comment.