Weechat Setup Tutorial

Written for Debian (originally based on Buster, works on Bullseye).

Some notes included for CentOS/RHEL.

Commands shown following # need to be run either as root or using sudo.

Commands shown following $ need to be run as your regular user.

Commands entered within WeeChat are always led by a forward slash: /

Any time text is shown inside < > , it denotes text that must be replaced with your own. For example, <password> would simply be replaced by your password. Do not include < > .

Comprehensive Official WeeChat Documentation is available on WeeChat's site.

This tutorial will walk you through:

You will need:

  • an online server, preferably with a static IP
  • a domain name
  • a wildcard SSL certificate that matches your domain name OR an SSL certificate that matches the full domain including the subdomain you will use
  • a wildcard DNS record for the domain OR a specific DNS record for the subdomain you will use
  • a functional (basic or better) webserver setup with Apache httpd
  • a terminal text editor (Nano or Vim, for example)

A terminal multiplexer such as Screen, Tmux, or Byobu will be handy for setting up the reverse proxy, although it's not necessary. If you have one, open it before you start this process so that once you have WeeChat running, you can open more virtual terminals and leave WeeChat running while you set up everything else.

---------------------------------------------------

Install WeeChat

(On CentOS/RHEL, WeeChat is in the repositories. Simply run: # dnf install weechat .)

Debian based systems follow these steps.

Steps taken from WeeChat.org. If you have something other than Debian Buster, the WeeChat Download page can help with specific repository listings.

  1. Install dependencies.
    # apt install dirmngr gpg-agent apt-transport-https

    These may already be installed.
  2. Create GnuPG directory.
    # mkdir ~/.gnupg
    # chmod 700 ~/.gnupg
  3. Set up repository keyrings.
    # mkdir -p /usr/local/share/keyrings
    # gpg --no-default-keyring --keyring /usr/local/share/keyrings/weechat-archive-keyring.gpg --keyserver hkps://keys.openpgp.org --recv-keys 11E9DE8848F2B65222AA75B8D1820DB22A11534E
  4. Create Weechat repository source list file AS ROOT:
    # echo "deb [signed-by=/usr/local/share/keyrings/weechat-archive-keyring.gpg] https://weechat.org/debian buster main" | tee /etc/apt/sources.list.d/weechat.list

    OR as regular user WITH SUDO:
    $ echo "deb [signed-by=/usr/local/share/keyrings/weechat-archive-keyring.gpg] https://weechat.org/debian buster main" | sudo tee /etc/apt/sources.list.d/weechat.list
  5. Update repository listings.
    # apt update
  6. Install Weechat packages.
    # apt-get install weechat-curses weechat-plugins weechat-python weechat-perl weechat-headless

Once install is complete, continue with setup!

Back to top of page

---------------------------------------------------

WeeChat Basic Setup

WeeChat is well documented for options and capabilities, although I didn't find a full step-by-step tutorial, which is the reason I put this together.

  1. Start WeeChat as your regular user (not root):
    $ weechat
  2. WeeChat terminal app opens, and one of the first handy things to do if you have a mouse on the screen is enabling it in WeeChat. This is simple with:
    /mouse enable
    • If you don't have a mouse, or prefer using the keyboard, keybindings to navigate and control buffers and windows are listed here.
    • Keep in mind that your terminal app or terminal multiplexer (if you're using one) may not pass keybindings properly! For example, multiplexer Byobu by default uses many of the same keys.
  3. Now you can add a server. I will demonstrate with my own server, TheCanadianHermit IRC. The following command adds a server that will be referred to as "thecdnhermit" with the actual address and port, and SSL (encryption) enabled. If you're adding a different server, replace the example information appropriately.
    /server add <thecdnhermit> <irc.thecdnhermit.com/6697> -ssl
  4. The default username will be your unix system username. You can change this with the command:
    /set irc.server.<thecdnhermit>.username <username>
  5. If you are changing your username, you may also want to change your alternate nicknames:
    /set irc.server.<thecdnhermit>.nicks <username>,<username1>,<username2>
  6. If you are already registered with the server, you can add SASL login info, including securing your password with:
    /set irc.server.<thecdnhermit>.sasl_username <username>
    /secure set <thecdnhermit>_sasl <password>
    /set irc.server.<thecdnhermit>.sasl_password ${sec.data.<thecdnhermit>_sasl}
  7. If you prefer to Identify with NickServ, or that is the only identification service the network provides, you will need to follow the next couple steps. (If the network does offer SASL authentication, I highly recommend using it as you are then authenticated AS you connect, versus NickServ authenticating AFTER you connect.)
    /secure set <thecdnhermit>_nickserv_pass <password>
    /set irc.server.<thecdnhermit>.command "/msg nickserv identify ${sec.data.<thecdnhermit>_nickserv_pass}"
    /set irc.server.<thecdnhermit>.command_delay 5
  8. You can now connect to this server with:
    /connect <thecdnhermit>
  9. If you set up SASL already, watch for "SASL authentication successful" to confirm that settings are correct.
  10. Once connected, you can join channels with:
    /join #<channel>
  11. And now you are connected to your IRC network. You can find your way around the network the same as always, with /join, /part, /query, /msg, /kick, /ban, /nick, etc. However, shortened services commands that you may be used to such as /ns (for /msg nickserv) are not available through WeeChat.
  12. You can view the settings list for your network by entering:
    /fset irc.server.<thecdnhermit>

    This will open a new buffer which will appear in the list on the left as "fset.fset". Open it with the mouse or appropriate keybindings. You should recognize a few of the settings here, as you set them before you connected to your network. You can change any setting you want or need to change, using the /set command as you have already done.
    For example, you can set the server to be automatically connected on startup with:
    /set irc.server.<thecdnhermit>.autoconnect on

    Or set the channels to automatically join on connection to the server:
    /set irc.server.<thecdnhermit>.autojoin #channel1,#channel2,##channel9

    At any point, you can use the command
    /help

    to view a list of commands, or
    /help <command>

    to get help with that specific command.
    Again, there is much more info in the official User Documentation.

Back to top of page

---------------------------------------------------

WeeChat Protocol Relay Setup

The greatest thing about WeeChat is its WeeChat relay protocol. Now that you have WeeChat connected to at least one IRC network, it can stay connected constantly and provide a relay for you to connect to from Glowing-Bear in any reasonably recent browser with an internet connection, or WeeChat-Android on your Android smartphone. Both of these apps can make for literally seamless IRC communications between devices while on the go, and with WeeChat-Android network changes are handled virtually invisibly with you likely not noticing a thing the majority of the time. So let's get started and set up the WeeChat relay!

  1. First, set up a relay password:
    /secure set relay_password <password>
  2. Now set the password to be used for the relay, with the command:
    /set relay.network.password ${sec.data.relay_password}
  3. And set up the relay (make sure you pick an available port! It does not have to be the same as below):
    /relay add weechat <9000>

The weechat buffer will show if the relay was added or if there was an error. If the relay was added, you can move on to the next step.

NOTE: If the system you are setting up Weechat on has direct access to the internet, these relay ports (such as the above 9000) must be firewalled and inaccessible from the internet. The following steps will allow each of these relays to be accessible through the common HTTPS port 443, which must be open to the internet.

Back to top of page

---------------------------------------------------

Reverse Proxying the WeeChat Relay with Apache httpd

This is assuming you have a basic Apache httpd webserver already set up, serving at least one website on SSL (https).

NOTE: Because you're setting up a reverse proxy, the WeeChat relay port itself (shown here as 9000) does NOT need to be opened to the internet. In fact, this reverse proxy setup is done explicitly to avoid opening the relay port to internet access. If this setup is used, all WeeChat relay ports should be blocked at the firewall.

You can use an existing virtual host and simply add the appropriate lines, enable the appropriate modules, and be set! Or you can create a brand new virtual host for the WeeChat websocket relay. I will describe both methods.

Method 1, using an existing virtual host. You would use this if you have an existing virtual host and don't see a point to creating a new one just to proxy for WeeChat.

  1. If you have multiple SSL virtual hosts, pick one that you want to use for the WeeChat relay. It could be your www subdomain, or any other. If you only have one, you can use that one. Basically, you want a virtual host block that starts with: <VirtualHost *:443>. You will need to use root or sudo to make this edit.
  2. Just before the end of that block (</VirtualHost>), insert the next two lines:
    ProxyPass        /<websocket_path> ws://localhost:<9000>/weechat
    ProxyPassReverse /<websocket_path> ws://localhost:<9000>/weechat
    • In place of <websocket_path>, enter what you want to be at the end of your access URL. For example, with the above settings, the full URL to access the websocket from Glowing-Bear would be:
      sub.domain.com:443/websocket_path
    • Make sure to use the same port as you set for your WeeChat relay earlier (shown as 9000 above).
  3. Save and close the file.
  4. Ensure Apache module proxy_wstunnel and any associated modules are enabled with:
    # a2enmod proxy_wstunnel

    Any other modules required will be enabled automatically. (This is how Apache2 on Debian is set up, Apache httpd on other Linux distributions may have a different method of enabling modules.)
  5. If you are running CentOS/RHEL: The default SELinux policy will prevent Apache httpd from communicating with the WeeChat relay. To fix this, run as root:
    # setsebool -P httpd_can_network_connect 1
  6. Reload apache2 config:
    systemctl reload apache2

Method 2, creating a new virtual host. This can be alot more complicated. It's easiest if you have a wildcard SSL certificate AND and wildcard DNS record, which I will not get into here. If you want to create a new host and don't have a wildcard SSL certificate AND a wildcard DNS record, you will have to either create those, OR create a wildcard SSL certificate and a host specific DNS record, OR create a host specific SSL certificate and DNS record. (I recommend a wildcard SSL certificate and a host specific DNS record.)

  1. Once either of those are done, you can carry on with creating a new virtual host. This can be either in an existing VirtualHost file (so far I have one file in /etc/apache2/sites-available/ that includes all my virtual hosts) or a standalone file just for this virtual host in that same folder. (I recommend against the standalone file; from my experience with Apache httpd from the Debian repositories, it works best with all virtual hosts in a single file.) Wherever you place it, the following is an example virtual host. This must be done with root.
    <VirtualHost *:443>
        ServerName <irc.mydomain.com>
        ServerAdmin <webmaster@mydomain.com>
        ErrorLog ${APACHE_LOG_DIR}/<ircmd>-error.log
        CustomLog ${APACHE_LOG_DIR}/<ircmd>-access.log combined
        DocumentRoot </var/www/mydomain>
        SSLEngine on
        SSLCertificateFile /etc/letsencrypt/live/<mydomain.com>/fullchain.pem
        SSLCertificateKeyFile /etc/letsencrypt/live/<mydomain.com>/privkey.pem
        ProxyPass	 /<myname> ws://localhost:<9000>/weechat
        ProxyPassReverse /<myname> ws://localhost:<9000>/weechat
    </VirtualHost>
    • The first and last lines must be exactly as shown, including the < >
    • In the ProxyPass lines, make sure to replace <myname> with your websocket path of choice, and use the same port as you set for your WeeChat relay earlier (shown as 9000)
    • If you have added this virtual host to a file that is already active, all you need to do is reload apache2 httpd after a couple more steps
    • If you create a new file, it must end in: .conf
    • If you created a new file for this virtual host in /etc/apache2/sites-available/, then you will have to enable it with the comnmand:
      a2ensite <mysite>
    • Where <mysite> is the name of the new file you created for the new virtual host (does not have to include .conf)
  2. Make sure Apache module proxy_wstunnel is enabled (plus any subsequently required modules) by running as root:
    # a2enmod proxy_wstunnel

    Any other modules required will be enabled automatically. (This is how Apache2 on Debian is set up, Apache httpd on other Linux distrobutions may have a different method of enabling modules.)
  3. If you are running CentOS/RHEL: The default SELinux policy will prevent Apache httpd from communicating with the WeeChat relay. To fix this, run as root:
    # setsebool -P httpd_can_network_connect 1
  4. Reload Apache httpd.
    # systemctl reload apache2

Your WeeChat instance is now accessible via the WeeChat protocol relay through the Apache httpd reverse proxy at: host.domain.com:443/websocket_path.

Back to top of page

---------------------------------------------------

Reverse Proxying the WeeChat Relay with Nginx

This is assuming you have a basic Nginx webserver already set up, serving at least one website on SSL (https).

NOTE: Because you're setting up a reverse proxy, the WeeChat relay port itself (shown here as 9000) does NOT need to be opened to the internet. In fact, this reverse proxy setup is done explicitly to avoid opening the relay port to internet access. If this setup is used, all WeeChat relay ports should be blocked at the firewall.

You can use an existing virtual host and simply add the appropriate lines and be set! Or you can create a brand new virtual host for the WeeChat websocket relay. I will describe both methods.

Method 1, using an existing active SSL (https) virtual host. You would use this if you have an existing active SSL (https) virtual host and don't see a point to creating a new one just to proxy for WeeChat.

  1. If you have multiple active SSL virtual hosts, pick one that you want to use for the WeeChat relay. It could be your www host, or any other. If you only have one, you can use that one. You will need to use root or sudo to edit this file.
  2. Open the file for the selected virtual host. For example, using Vim as root:
    # vim /etc/nginx/sites-available/default
    • This would open the file for the default virtual host.
  3. Just above the server block (make sure it's not inside a server block!), add the line:
    limit_req_zone $binary_remote_addr zone=weechat:10m rate=5r/m;
  4. Inside the server block for SSL (below the line listen 443 ssl;), you will have to create a location block. Use the following template:
    location /<myname> {
        proxy_pass http://localhost:<9000>/weechat;	# Replace <9000> with the relay port you set earlier
        proxy_set_header Host $host;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;		# These two lines ensure that 
        proxy_set_header Connection "Upgrade";		# a websocket is used
        proxy_read_timeout 604800;				# Prevent idle disconnects
        proxy_set_header X-Real-IP $remote_addr;		# Let WeeChat see the client's IP
        limit_req zone=weechat burst=1 nodelay;		# Brute force prevention
    }
    • In the first line, replace <myname> with your websocket path of choice, whether that's the default weechat, your name, or another word that you have chosen
    • In the second line,as already noted in the comment on that line, replace <9000> with the same port number as you set for your Weechat relay earlier
    • Save the file and close the editor
  5. Test the config for errors:
    # nginx -t
    • If you've done everything properly, there should be no errors.
  6. Restart nginx:
    # systemctl restart nginx.service

Method 2, creating a new virtual host. This can be alot more complicated. It's easiest if you have a wildcard SSL certificate AND a wildcard DNS record, which I will not get into here. If you want to create a new host record and don't have a wildcard SSL certificate AND a wildcard DNS record, you will have to either create those, OR create a wildcard SSL certificate and a host specific DNS record, OR create a host specific SSL certificate and DNS record. (I recommend a wildcard SSL certificate and a host specific DNS record.)

  1. First, you'll need to create the file for the virtual host. Pick a name, and create it in /etc/nginx/sites-available/. For example, if you use Vim, the command would be:
    # vim /etc/nginx/sites-available/<weechat>
    • Where <weechat> is your filename of choice
    • If you use Nano, replace vim with nano
  2. The following codeblock is a very simple virtual host that will not serve any webpage, but simply proxy the WeeChat relay to the client through port 443. Enter the following, changing as required according to the following instructions:
    limit_req_zone $binary_remote_addr zone=weechat:10m rate=5r/m;		# Brute force prevention (part 1 of 2)
    server {
    	listen 443 ssl;
    	server_name <host>.<domain>.<tld>;
    	ssl_certificate </full/path/to/appropriate/certificate>;
    	ssl_certificate_key </full/path/to/appropriate/certificate_key>;
    	location /<myname> {
    		proxy_pass http://localhost:<9000>/weechat;		# Replace <9000> with the relay port you set earlier
    		proxy_set_header Host $host;
    		proxy_http_version 1.1;
    		proxy_set_header Upgrade $http_upgrade;			# These two lines ensure that
    		proxy_set_header Connection "Upgrade";			# a websocket is used
    		proxy_read_timeout 604800;				# Prevent idle disconnects
    		proxy_set_header X-Real-IP $remote_addr;		# Let WeeChat see the client's IP
    		limit_req zone=weechat burst=1 nodelay;			# Brute force prevention (part 2 of 2)
    	}
    }
    1. In the server_name line, replace <host>.<domain>.<tld> with your own Fully Qualified Domain Name. For example, using my IRC server, that line would be: server_name irc.thecdnhermit.com;
    2. In the ssl_certificate line, you need to point to the appropriate certificate file. If you're using a wildcard certificate AND LetsEncrypt (as I do), the path would be similar to:
      /etc/letsencrypt/live/thecdnhermit.com/fullchain.pem
      (where thecdnhermit.com would be your domain)
    3. Similarly, in the ssl_certificate_key line, you need to point to the appropriate certificate key file. If you're using a wildcard certificate AND LetsEncrypt, the path would be similar to:
      /etc/letsencrypt/live/thecdnhermit.com/privkey.pem
      (where thecdnhermit.com would be your domain)
    4. In the location line, <myname> should be replaced with your websocket path of choice, whether that's the default weechat, your name, or another word that you have chosen
    5. And the last adjustment here is in the proxy_pass line, as already noted in the comment on that line: ensure the port (shown as 9000) is the same as you set for your WeeChat relay earlier
    6. Save the file and close the editor
  3. Enable the virtual host by creating a symlink in /etc/nginx/sites-enabled/:
    # ln -s /etc/nginx/sites-available/<weechat> /etc/nginx/sites-enabled/<weechat>
    • Where both instances of <weechat> is the name of the virtual host file you just created
  4. Test the config for errors:
    # nginx -t
    • If you've done everything properly, there should be no errors.
  5. Restart nginx:
    # systemctl restart nginx.service

Your WeeChat instance is now accessible via the WeeChat protocol relay through the Nginx reverse proxy at: host.domain.com:443/websocket_path.

Back to top of page

---------------------------------------------------

Set Up WeeChat To Run As A Daemon

This isn't very difficult, and I will describe the way to do it. Once this is done, as long as your server is up and online, your WeeChat instance will be connected and available for you to connect to.

  1. Log in to your WeeChat server as root. If you can't log in as root, then the following commands must be run with sudo.
  2. Using your text editor of choice, create the following file:
    /etc/systemd/system/weechat@.service

  3. Copy and paste the following code into the file:
    [Unit]
    Description=%i's Weechat Instance
    Wants=network.target
    After=syslog.target network-online.target
    
    [Service]
    Type=simple
    User=%i
    Group=%i
    ExecStart=/usr/bin/weechat-headless --daemon
    ExecReload=/bin/kill -HUP $MAINPID
    KillMode=process
    Restart=on-failure
    
    [Install]
    WantedBy=multi-user.target
  4. Save and close the file.
  5. If you still have WeeChat running under your personal user, switch to that virtual terminal and close it.
    • In WeeChat, enter the following command:

    /quit
  6. Return to root, and enter the following commands:
    # systemctl enable weechat@<your-unix-username>.service
    # systemctl start weechat@<your-unix-username>.service
    • Of course, <your-unix-username> is the Linux username you set up WeeChat under.
    This enables a service to run on boot and then starts the same service, which uses the service template file created above and links it to the user named after the @ sign, so all appropriate settings files will be loaded with this instance.
WeeChat will now run automatically when the system boots, and will automatically connect to the networks you've set up. Clients such as Glowing-Bear or WeeChat-Android will connect any time the WeeChat instance is available when they are open. You should now be consistently connected to IRC, thanks to WeeChat!

Back to top of page

---------------------------------------------------

WeeChat-Android Install, Setup, and Use

The easiest way to use WeeChat on your Android smartphone is with WeeChat-Android, which is avaliable both through the open source app repositories of F-Droid, or from the Google Play Store. In either app, simply search for and install Weechat-Android.

Setting up WeeChat-Android is fairly straightforward. Start by opening WeeChat-Android. If your version is newer than 1.7.1, these instructions may be slightly different.

  1. Tap the three dots button in the upper right.
  2. Tap Settings.
  3. Tap Connection.
  4. Tap Connection type, then select WebSocket (SSL).
  5. Tap WebSocket path, type into the box whatever you set as the <websocket_path> in the reverse proxy settings, then tap OK.
  6. Tap Relay host, type in the base URL to your reverse proxy, and tap OK. (Example: sub.domain.com)
  7. Tap Relay port, type in 443, tap OK.
  8. Tap Relay password, type in the password you set when you set up the relay, then tap OK.
  9. Ensure both Reconnect on connection loss and Connect on system boot are both selected.
  10. Tap the back button (arrow) in the upper left corner, twice.
  11. Tap the three dots button in the upper right.
  12. Tap Connect.

WeeChat-Android should now be connected to your hosted WeeChat instance. It will start and connect when your device is started, and reconnect on connection loss for consistent connection across network changes.

You can peruse the Settings menus for more options, such as how the Buffer list appears and behaves, Look & feel options such as Text size, Prefix alignment (No alignment is most efficient on small screens), Enclose nicknames which helps make conversations more easily readable when No alignment is set, and a number of other settings.

Some basic usage tips:

  • WeeChat-Android stays open most consistently when the Connection Status notification is enabled under three dots button, Settings, Notifications.
  • When connected, tapping the three lines button in the upper left will show you all available buffers. Depending on how you have the Buffer list settings set, you may see all buffers, or you may only see conversation buffers (channel and query buffers). You can also set it to sort buffers so that the top has the most unread messages, and each one down has less.
  • You can swipe side to side between recently opened buffers.
  • Under three dots button, Settings, File sharing, it is possible to set up to upload files / images to a filehost to share in any conversation buffer. The settings here vary depending on the filehost.
  • The bell button in the upper right will show the number of notifications (when they exist). Tapping this button when it shows a number will take you to the first conversation where you have a notification for. If more than one, each consecutive tap will take you to the next conversation.
  • The cat button next to the bell will allow you to search the current buffer.
  • The paper airplane button in the lower right, or just above the keyboard on the right, is the Send button.
  • The next button with an arrow is the nick completion button. Starting typing a nick and then tapping this button will begin cycling through matching nicks with each tap.
  • And the last button on the bottom, the "cat with the curled tail", is referred to as the Paperclip button and two actions set under three dots button, Settings, Buttons. It's for sharing files / images if File sharing is set up.
  • Finally, if the Paper Airplane button (Send button) has a red dot on it, that means that you are disconnected, which does happen momentarily when the phone switches between networks.

Enjoy being always connected!

Back to top of page

---------------------------------------------------

Using Glowing-Bear to Connect to WeeChat From Any Online Browser

This can be very simple, using Glowing-Bear's own site to access your WeeChat instance:

  1. Go to Latest.Glowing-Bear.org (or www.Glowing-Bear.org for the previous version).
  2. In the WeeChat relay hostname box, enter your WeeChat instance address in the following format:
    <host.domain.com>:443/<websocket_path>
    • The domain is the same as the ServerName in the Apache httpd VirtualHost OR Nginx VirtualHost you used to set up the reverse proxy.
    • The :443 says to use port 443.
    • <websocket_path> is the same as what you set in that same reverse proxy.
  3. Enter your relay password in the WeeChat relay password box. This would be the password you set up in WeeChat Relay Protocol Setup, above.
  4. Ensure the Encryption box is selected.
  5. If this is your device, you can select Save password in your browser, and then another option will appear to Automatically connect. If selected, you will automatically be connected as soon as you open this website.
  6. Click the Connect button.

Some tips for using Glowing-Bear:

  • Buffer list is on the left, user list (for conversation buffers) on the right.
  • In the upper right is a gear link, which opens some settings where you can select the font, font size, colors theme, Imgur login info, and some other viewing and handling options. Click the Close button at the bottom when done.
  • If you want to disconnect from your WeeChat relay, click the Power button in the upper right corner.
  • In the lower right, there is a button to upload an image to Imgur, which you can then share the link to in the current buffer.
  • Text is sent when the Enter key is pressed, or the Paper Airplane button is clicked.

Glowing-Bear has options listed on the main page, including Getting Started info, Usage instructions, Install app information, and some info on how to Get involved, where they link to their Github project page where you can download and install it for self-hosting.

If you're using Glowing-Bear on your iOS device, you can set up a shortcut on your home screen.

  1. In Safari, open your Glowing-Bear site of choice.
  2. Tap the browser's Share button.
  3. Find and tap Add to Home Screen.
  4. Tap the Add button (after making adjustments, if necessary).
  5. Open Glowing-Bear directly from your home screen.
  6. Enter connection info (as described earlier), ensure Save password in your browser AND Automatically connect are selected.
  7. Glowing-Bear will immediately attempt to connect. If there is an error, confirm that you have entered the correct connection info.

Keep in mind that iOS does not allow apps to run in the background, so the only way Glowing-Bear will update is if the screen is on and Glowing-Bear is active. Saving the password and setting automatic connection ensures that Glowing-Bear will reconnect as soon as it is activated, so even with no notifications, you will easily be able to catch up with conversations!

Back to top of page

---------------------------------------------------

Lith on iOS

Lith is a WeeChat client app for iOS. So far it's only available through Apple TestFlight, as it hasn't been fully tested to meet Apple's approval for Appstore release. It does not have notifications, and occasionally has a bug from an update, but it does allow you to connect to your WeeChat instance from an iOS device.

If you're looking for something more reliable (although still no notifications), I recommend using Glowing-Bear in your device's browser. The last portion of the section on Glowing-Bear goes over setting up Glowing-Bear for easy use on your iOS device.

To get started with Lith, on your iOS device:

  1. Go to https://github.com/LithApp/Lith#binary-packages and click the link for Apple Testflight.
  2. If you need to install Testflight, tap the link to open the App Store and install Testflight, then close the App Store.
  3. Back in the browser app, move to Step 2, Join the Beta, and tap Start Testing. Allow or disallow Testflight notifications (your preference).
  4. Tap the Continue button, then beside Lith IRC, tap the Install button.
  5. After it's installed, tap the Open button, or close Testflight and open Lith from your home screen.
  6. You may have a From the Developer message come up that lists recent updates and changes. Read it if you like, then tap the Next button.
  7. Tap the Start Testing button at the bottom of the next screen instructing you on how to Share Feedback.
  8. Tap the three lines button in the upper left, or swipe from the left side of the screen, then tap the gear icon that appears at the top.
  9. Under the Connection tab, enter the appropriate data in the fields (keep in mind that the app is still in "beta / testing" stage, there may be some glitching of the settings screen when the keyboard is brought up):
    • Hostname: <sub.domain.com>
    • Port: 443
    • SSL: Ensure it is selected (there is an X in the box)
    • Allow self-signed certificates: If you know you need this, select it; otherwise leave it deselected (blank box)
    • Password: Your WeeChat relay password
    • Use Handshake: Selected
    • Use WeeChat compression: Selected
    • Use WebSockets to connect: Selected
    • Websockets endpoint: <websocket_path> (as set in the Reverse Proxy Setup earlier in this tutorial)
  10. The Interface tab has a number of settings to customize appearance and usage.
  11. When done adjusting settings, tap the OK at the bottom.
  12. A box will pop up that says: "Lith" would like to find and connect to devices on your local network. Tap the Allow button to allow Lith to access available network services (mobile or wifi networks).

Lith will attempt to connect, and if successful, you will be able to swipe from the left (or tap the three lines button in the upper left) to bring up your WeeChat buffer list. Once in a channel, swiping from the right (or tapping the smiley face button in the upper right) will bring up the list of users in the channel. The text entry box will be at the bottom. There is a nick-completion button to the left of the text entry box (looks approximately like: ->|). There's also an image button in the lower right which will allow you to upload an image to Imgur and share the resulting link.

Keep in mind that due to the way iOS prevents apps from running in the background (other than some such as music players), and due to the fact that Lith is still in the testing stages, there are no notifications. The only way to know about new messages is to bring Lith to the front and check for new messages.

Back to top of page

---------------------------------------------------

Adding More Users (Family Members or other Trusted People)

Now that you've set this all up once, you're probably wondering how hard it is to get your family or group of friends in on this, and it's not difficult, as long as you trust them! Keep in mind that WeeChat does allow direct shell access to the host system with the /exec command, so if you do not want your system to be compromised, don't give WeeChat access to anyone you don't fully trust!

That said, if you have set up an IRC server and want your family connected to it via WeeChat, and they aren't very tech savvy but keep track of their devices (or they're just plain honest), it is fairly straightforward to set up.

  1. On your server, create a user account for the user(s) you would like to add to WeeChat.
  2. Individually log in to each new user and:
    1. Set up Weechat for that user.
    2. Set up a Custom WeeChat Relay for that user. Make sure to use a free port and a custom password for the new user.
    3. Add a Custom <websocket_path> to point to this user's WeeChat Relay port.
      • If you use Apache httpd, follow Method 1 and simply add another set of ProxyPass lines using a new websocket_path directed to the new user's WeeChat relay port.
      • If you use Nginx, follow Method 1 and simply add a new location block, where the the location line is unique to the new user (eg. location /<newuser>, and the port in the proxy_pass line is the same as the port you set for their WeeChat relay.
    4. Set New User's WeeChat Instance to Run as a Daemon so it's always available.
    5. Repeat as many times a necessary.
  3. Each added user will be able to connect via Glowing-Bear or WeeChat-Android when set up appropriately.

Back to top of page

---------------------------------------------------

Final Notes

Thank you for at least reading through my tutorial for WeeChat. I hope it helps to simplify a process that can appear quite daunting when first looking through WeeChat's official documentation.

If you have any comments or questions, would like to see something added, or just want to pop in, you can find me in chat via the Chat link in the menu. Maybe I'll see you there?