= Background = 

https://social.mayfirst.org is MF/PL's [https://gnu.io/ GnuSocial] instance.

ticket:12504 contains information about upgrading gnusocial from 1.1.x to 1.2.x.

ticket:10723 is contains a (somewhat disorganized) hodgepodge of information about gnusocial administrivia

= Web Administration = 

The administrative credentials are stored in keyringer.  Look for social.mayfirst.org.

= General deployment and updates =

social's web front end is apache with php5-fpm.  It's the same basic setup we use on moshes.

social's code is stored in a git repository: {{{git://git.mayfirst.org/mfpl/gnusocial}}}.  Branches in this repository are:
* master - based on the upstream master branch, with no modifications
* mfpl-master.  A copy of the master branch, with mfpl modifications
* mfpl-1.1.x.  A copy of the upstream 1.1.x branch, with mfpl modifications
* mfpl-1.2.x.  A copy of the upstream 1.2.x branch, which we've never used.

We deploy code from tags on the mfpl-master branch.  For example
{{{
0 gnusocial@howard:~/social.mayfirst.org/web$ git status
HEAD detached at social-20170905.1

# social-20170905.1 is a signed tag
}}}

For updates, the general idea is to

* clone {{{git://git.mayfirst.org/mfpl/gnusocial}}}.  Call this remote `gmo'
* clone the vendor git repository.  Call this remote `origin'
* move changes from origin/master -> mfpl-master
* test.  At the moment, you'll need to set up your own environment for testing.
* create a signed tag on the commit you'd like to deploy.
* {{{git push gmo mfpl-master; git push gmo --tags}}}
* on howard, {{{git fetch gmo}}}, then checkout the tag.

In short, the preferred workflow is to do the work on a test instance, then deploy the changes to howard.

= Queue Daemons = 

Queue daemons (aka scripts/queuedaemon.php) are gnusocial background processes.  Queue daemons push (and pull) status changes to (and from) other ostatus sites.  If the queue daemons aren't running, then updates don't propagate, and the queue becomes backlogged.

queuedaemon is run via an sv service: {{{/etc/sv/queuedaemon}}}

= Stuck/Stale queue items =

Gnusocial uses a queueing system to manage background tasks.  The queue lives in a mysql table called {{{queue_item}}}.  Sometimes, things get stuck in the queue and have to be cleaned out manually.  ticket:13087 explains how to do this.


= Setting up Meteor real-time updates over https

In order to have real-time updates in the web interface of GNU Social one needs to enable the Meteor plugin (part of GNU Social) and set up a Meteor server. We want to serve Meteor over https, and opt to use Apache for proxying the URLs for this. In this way the traffic will be encrypted, and also Meteor won't be directly available externally, which always feels safer :-)


The Meteor server can be downloaded from http://meteorserver.org/#download - I used the latest stable source package. Unpack the source code in some suitable directory, then copy the sample config to its place:

{{{
cp meteord.conf.dist /etc/meteord.conf
}}}

At the beginning of this file you need to add these configuration options. It means that the Meteor server will be listening to localhost for both controller (sending messages) and subscriber (client waiting for messages). The subscriber is the web browser, but this will be proxied via apache, which is why we can bind to localhost.

{{{
ControllerIP 127.0.0.1
ControllerPort 4671
SubscriberIP 127.0.0.1
SubscriberPort 8085
SubscriberDocumentRoot /path/to/your/meteor/public_html/
}}}

Set the `SubscriberDocumentRoot` to where you unpacked the meteor source and append `/public_html/`.  If you are serving over https (which you should) you need to edit `public_html/meteor.js` and change the `scheme:` setting from `http` to `https`.

Next set up Apache proxying in the place for your GNU Social virtual host:

{{{
  # Proxy for Meteor server
  <IfModule mod_proxy.c>
    ProxyPass /poll.html http://127.0.0.1:8085/poll.html
    ProxyPassReverse /poll.html http://127.0.0.1:8085/poll.html
    ProxyPass /stream.html http://127.0.0.1:8085/stream.html
    ProxyPassReverse /stream.html http://127.0.0.1:8085/stream.html
    ProxyPass /meteor.js http://127.0.0.1:8085/meteor.js
    ProxyPassReverse /meteor.js http://127.0.0.1:8085/meteor.js
    ProxyPass /push/ http://127.0.0.1:8085/push/
    ProxyPassReverse /push/ http://127.0.0.1:8085/push/
  </IfModule>
}}}

You also need to add the proper modules to apache and restart:

{{{
a2enmod proxy
a2enmod proxy_http
service apache2 restart
}}}

Finally enable the plugins in the GNU Social `config.php` file:

{{{
addPlugin('Realtime');
addPlugin('Meteor', array('webserver' => 'your.gnu-social.site.com',
    'webport' => '443',
    'controlserver' => '127.0.0.1',
    'controlport' => '4671',
    'protocol' => 'https'
    ));
}}}

meteord runs as sv service.  See {{{howard:/etc/sv/meteor}}}