Commit 49c01141 authored by John Kristensen's avatar John Kristensen

Initial port of admin manual to Sphinx

A port of the existing admin manual over to reStructuredText and using
Sphinx to generate the documentation to see if it would be a suitable
replacement for the existing php generated method.
parent 3575fc33
Backing Up and Restoring
========================
Backing Up
----------
It is important to back up GNU social regularly. If you need to revert to an
old backup you will lose any newer notices. Any follows that happened since
then will result in mismatched information on your server and remote servers.
You should also back up immediately prior to any upgrade. This is especially
important if you are following the *nightly* branch where serious bugs might
slip through.
There are two parts to your GNU social installation and they most *both* be
backed up at the same time.
1. The files hosted by your webserver. This is a mixture of GNU social code and
user data. This a directory probably located somewhere like
``/var/www/social``.
2. The contents of the MariaDB/MySQL database.
Web Files
^^^^^^^^^
You don't need to do anything fancy. Just make sure you have a copy of the
folder. If you're using a commercial web hosting service there is probably a
button you can press to download an archive of all your files. Note that this
normally does *not* include your database.
If you have shell access on the server, assuming the GNU social folder is
located at ``/var/www/social``, you can make a compressed backup in your home
directory like this::
TIMESTAMP=$(date +%Y%m%d-%H%M)
cd /var/www
tar -Jcf "~/$TIMESTAMP-social-www.tar.xz" --exclude=.git social
If you are serving files straight out of the git repository this will back up
only the currently checked out copy, not the entire history. (Using a git
repository this way is not recommended as you may cause chaos in your database
if you accidentally check out the wrong thing.)
Database
^^^^^^^^
There are many different tools and techniques for backing up MySQL databases.
If you're using a commercial web hosting service there will probably be
somewhere in the web interface where you can download a copy of the GNU social
database.
If you have shell access the simplest way to create a backup is using the tool
*mysqldump*. ::
TIMESTAMP=$(date +%Y%m%d-%H%M)
mysqldump -u "database_username" -p "database_name" | xz -c - > "~/$TIMESTAMP-social.sql.xz"
You will be prompted for a password. Type in the password for the MySQL user.
Restoring from a Backup
-----------------------
1. Stop the queue daemons if they're running.
2. Restore the web files.
3. Restore the database.
4. Restart the queue daemons.
If you followed the examples above you might type the following::
cd /var/www/social
# Stop the daemons
bash ./scripts/stopdaemons.sh
# Delete and restore the web files
rm -r *
cd ..
tar -Jxf ~/20160130-1200-social-www.tar.xz
# Recreate the database (using MySQL root account)
mysqladmin -u root -p drop social
mysqladmin -u root -p create social
mysql -u root -p social
# Inside mysql client
GRANT ALL on social.* TO 'social'@'localhost' IDENTIFIED BY 'the_old_password';
exit
# Restore the database as the GNU social MySQL user
xzcat ~/20160130-1200-social.sql.xz | mysql -u social -p social
# Restart the queue daemons
cd social
bash ./scripts/startdaemons.sh
Contributing
============
Translations
------------
For info on helping with translations, see the `platform currently in use`_ for
translations.gettext system. If you for some reason do not wish to sign up to
the Transifex service, you can review the files in the ``locale/``
sub-directory of GNU social. Each plugin also has its own translation files.
.. _platform currently in use: https://www.transifex.com/projects/p/gnu-social/
To get your own site to use all the translated languages, and you are tracking
the git repo, you will need to install at least 'gettext' on your system and
then run::
$ make translations
Admin Manual
============
Contents:
.. toctree::
:maxdepth: 2
installing_gnu_social
using_queue_daemons
backing_up_and_restoring
upgrading_your_installation
protocol_overview
contributing
This diff is collapsed.
Protocol Overview
=================
GNU social runs primarily on voodoo magic. If anybody knows better please
advise.
Upgrading Your Installation
===========================
Nightly or GNU social 1.1.x to GNU social 1.2.x
-----------------------------------------------
If you are tracking the GNU social git repository, we currently recommend using
the "master" branch (or nightly if you want to use latest features) and follow
this procedure:
1. Back up your data. The StatusNet upgrade discussions below have some
guidelines to back up the database and files (mysqldump and rsync).
2. Stop your queue daemons (you can run this command even if you do not use the
queue daemons)::
$ bash scripts/stopdaemons.sh
3. Run the command to fetch the latest sourcecode::
$ git pull
If you are not using git we recommend following the instructions below for
upgrading "StatusNet 1.1.x to GNU social 1.2.x" as they are similar.
4. Run the upgrade script::
$ php scripts/upgrade.php
The upgrade script will likely take a long time because it will upgrade the
tables to another character encoding and make other automated upgrades. Make
sure it ends without errors. If you get errors, create a new issue on the
`GNU social project page`_.
.. _GNU social project page: https://git.gnu.io/gnu/gnu-social/issues
5. Start your queue daemons again (you can run this command even if you do not
use the queue daemons)::
$ bash scripts/startdaemons.sh
6. Report any issues at https://git.gnu.io/gnu/gnu-social/issues
If you are using ssh keys to log in to your server, you can make this procedure
pretty painless (assuming you have automated backups already). Make sure you
"cd" into the correct directory (in this case "htdocs") and use the correct
login@hostname combo::
ssh social@domain.example 'cd htdocs \
&& bash scripts/stopdaemons.sh \
&& git pull \
&& time php scripts/upgrade.php \
&& bash \
scripts/startdaemons.sh'
.. todo:: remove href from login@hostname
StatusNet 1.1.x to GNU social 1.2.x
-----------------------------------
We cannot support migrating from any other version of StatusNet than 1.1.1. If
you are running a StatusNet version lower than this, please follow the upgrade
procedures for each respective StatusNet version.
You are now running StatusNet 1.1.1 and want to migrate to GNU social 1.2.x.
Beware there may be changes in minimum required version of PHP and the modules
required, so review the INSTALL file (php5-intl is a newly added dependency for
example).
**Before you begin: Make backups**. Always make backups. Of your entire
directory structure and the database too. All tables. All data. Alles.
1. Make a backup of everything. To backup the database, you can use a variant
of this command (you will be prompted for the database password)::
$ mysqldump -u dbuser -p dbname > social-backup.sql
2. Stop your queue daemons. ::
$ bash scripts/stopdaemons.sh
Not everyone runs queue daemons, but the above command won't hurt.
3. Unpack your GNU social code to a fresh directory. You can do this by cloning
our git repository::
$ git clone https://git.gnu.io/gnu/gnu-social.git gnusocial
4. Synchronize your local files to the GNU social directory. These will be the
local files such as avatars, config and files:
* ``avatar/*``
* ``file/*``
* ``local/*``
* ``.htaccess``
* ``config.php``
This command will point you in the right direction on how to do it::
$ rsync -avP statusnet/{.htaccess,avatar,file,local,config.php} gnusocial/
5. Replace your old StatusNet directory with the new GNU social directory in
your webserver root.
6. Run the upgrade script::
$ php scripts/upgrade.php
The upgrade script will likely take a long time because it will upgrade the
tables to another character encoding and make other automated upgrades. Make
sure it ends without errors. If you get errors, create a new issue on the
`GNU social project page`_.
.. _GNU social project page: https://git.gnu.io/gnu/gnu-social/issues
7. Start your queue daemons::
$ bash scripts/startdaemons.sh
8. Report any issues at https://git.gnu.io/gnu/gnu-social/issues
Using Queue Daemons
===================
Queues and Daemons
------------------
Some activities that GNU social needs to do, like broadcast OStatus, SMS, XMPP
messages and TwitterBridge operations, can be 'queued' and done by off-line
bots instead.
Two mechanisms are available to achieve offline operations:
* New embedded OpportunisticQM plugin, which is enabled by default
* Legacy queuedaemon script, which can be enabled via config file.
OpportunisticQM plugin
^^^^^^^^^^^^^^^^^^^^^^
This plugin is enabled by default. It tries its best to do background jobs
during regular HTTP requests, like API or HTML pages calls.
Since queueing system is enabled by default, notices to be broadcasted will be
stored, by default, into DB (table ``queue_item``).
Whenever it has time, OpportunisticQM will try to handle some of them.
This is a good solution whether you:
* have no access to command line (shared hosting)
* do not want to deal with long-running PHP processes
* run a low traffic GNU social instance
In other case, you really should consider enabling the queuedaemon for
performance reasons. Background daemons are necessary anyway if you wish to use
the Instant Messaging features such as communicating via XMPP.
queuedaemon
^^^^^^^^^^^
If you want to use legacy queuedaemon, you must be able to run long-running
offline processes, either on your main Web server or on another server you
control. (Your other server will still need all the above prerequisites, with
the exception of Apache.) Installing on a separate server is probably a good
idea for high-volume sites.
1. You'll need the "CLI" (command-line interface) version of PHP installed on
whatever server you use.
Modern PHP versions in some operating systems have disabled functions related
to forking, which is required for daemons to operate. To make this work, make
sure that your php-cli config (``/etc/php5/cli/php.ini``) does NOT have these
functions listed under 'disable_functions':
* pcntl_fork, pcntl_wait, pcntl_wifexited, pcntl_wexitstatus,
pcntl_wifsignaled, pcntl_wtermsig
Other recommended settings for optimal performance are:
* ``mysqli.allow_persistent = On``
* ``mysqli.reconnect = On``
2. If you're using a separate server for queues, install GNU social somewhere
on the server. You don't need to worry about the ``.htaccess`` file, but
make sure that your ``config.php`` file is close to, or identical to, your
Web server's version.
3. In your config.php files (on the server where you run the queue daemon), set
the following variable::
$config['queue']['daemon'] = true;
4. On the queues server, run the command ``scripts/startdaemons.sh``.
This will run the queue handlers:
queuedaemon.php
polls for queued items for inbox processing and pushing out to OStatus,
SMS, XMPP, etc.
imdaemon.php
if an IM plugin is enabled (like XMPP)
(plugins)
other daemons, like TwitterBridge ones, that you may have enabled
These daemons will automatically restart in most cases of failure including
memory leaks (if a memory_limit is set), but may still die or behave oddly if
they lose connections to the XMPP or queue servers.
It may be a good idea to use a daemon-monitoring service, like 'monit', to
check their status and keep them running.
All the daemons write their process IDs (pids) to ``/var/run/`` by default.
This can be useful for starting, stopping, and monitoring the daemons. If you
are running multiple sites on the same machine, it will be necessary to avoid
collisions of these PID files by setting a site-specific directory in
``config.php``::
$config['daemon']['piddir'] = __DIR__ . '/../run/';
It is also possible to use a STOMP server instead of our kind of hacky
home-grown DB-based queue solution. This is strongly recommended for best
response time, especially when using XMPP.
......@@ -12,6 +12,7 @@ Contents:
:maxdepth: 2
user/index
admin/index
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment