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.
This commit is contained in:
parent
3575fc337d
commit
49c0114104
95
docs/admin/backing_up_and_restoring.rst
Normal file
95
docs/admin/backing_up_and_restoring.rst
Normal file
|
@ -0,0 +1,95 @@
|
||||||
|
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
|
17
docs/admin/contributing.rst
Normal file
17
docs/admin/contributing.rst
Normal file
|
@ -0,0 +1,17 @@
|
||||||
|
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
|
14
docs/admin/index.rst
Normal file
14
docs/admin/index.rst
Normal file
|
@ -0,0 +1,14 @@
|
||||||
|
Admin Manual
|
||||||
|
============
|
||||||
|
|
||||||
|
Contents:
|
||||||
|
|
||||||
|
.. toctree::
|
||||||
|
:maxdepth: 2
|
||||||
|
|
||||||
|
installing_gnu_social
|
||||||
|
using_queue_daemons
|
||||||
|
backing_up_and_restoring
|
||||||
|
upgrading_your_installation
|
||||||
|
protocol_overview
|
||||||
|
contributing
|
474
docs/admin/installing_gnu_social.rst
Normal file
474
docs/admin/installing_gnu_social.rst
Normal file
|
@ -0,0 +1,474 @@
|
||||||
|
Installing GNU social
|
||||||
|
=====================
|
||||||
|
|
||||||
|
Prerequisites
|
||||||
|
-------------
|
||||||
|
|
||||||
|
Selecting a branch
|
||||||
|
^^^^^^^^^^^^^^^^^^
|
||||||
|
GNU social has three different branches of development offering a range of
|
||||||
|
choices between stability and the latest features.
|
||||||
|
|
||||||
|
1.2.x
|
||||||
|
This is the current stable release. The code has been tested for a while.
|
||||||
|
|
||||||
|
master
|
||||||
|
``master`` receives more frequent updates and is usually working well.
|
||||||
|
|
||||||
|
nightly
|
||||||
|
``nightly`` gets updated the most but is not always working.
|
||||||
|
|
||||||
|
When you download the source code in :ref:`getting-it-up-and-running` you will
|
||||||
|
need to know which branch you want to install. You can always move to a more
|
||||||
|
unstable branch but going backwards is not guaranteed to work.
|
||||||
|
|
||||||
|
If you want to use `Qvitter`_ — that's the plugin that makes GNU social look
|
||||||
|
like Twitter — be aware that it is tested against GNU social nightly. If you
|
||||||
|
are using a different branch and having problems with that plugin try upgrading
|
||||||
|
to nightly.
|
||||||
|
|
||||||
|
Web server configuration
|
||||||
|
^^^^^^^^^^^^^^^^^^^^^^^^
|
||||||
|
You should use HTTPS to encrypt all communications with your GNU social
|
||||||
|
instance. Until recently it cost money to get a trusted certificate but now the
|
||||||
|
Let's Encrypt project enables you to `obtain a trusted certificate at no
|
||||||
|
cost`_.
|
||||||
|
|
||||||
|
If you are thinking about starting with HTTP and setting up encryption later,
|
||||||
|
don't do that. You may have problems if you start with HTTP and later move to
|
||||||
|
HTTPS.
|
||||||
|
|
||||||
|
If you want to use Qvitter be aware that it only supports installations that
|
||||||
|
are installed directly on the domain. That is, the URL to access GNU social
|
||||||
|
needs to be ``https://www.some.domain/`` and not
|
||||||
|
``https://www.some.domain/gnusocial/``. It also requires you to have Fancy URLs
|
||||||
|
enabled. If you're using apache that means you need mod_rewrite and the ability
|
||||||
|
to use ``.htaccess`` files.
|
||||||
|
|
||||||
|
PHP modules
|
||||||
|
^^^^^^^^^^^
|
||||||
|
The following software packages are *required* for this software to run
|
||||||
|
correctly.
|
||||||
|
|
||||||
|
PHP 5.5+
|
||||||
|
For newer versions, some functions that are used may be disabled by default,
|
||||||
|
such as the ``pcntl_*`` family. See the section on
|
||||||
|
:doc:`using_queue_daemons`.
|
||||||
|
|
||||||
|
.. todo:: remove italics from Using Queue Daemons link
|
||||||
|
|
||||||
|
MariaDB 5+
|
||||||
|
GNU Social uses, by default, a MariaDB server for data storage. Versions 5.x
|
||||||
|
and 10.x have both reportedly worked well. It is also possible to run MySQL
|
||||||
|
5.5+.
|
||||||
|
|
||||||
|
Web server
|
||||||
|
Apache, lighttpd and nginx will all work. CGI mode is recommended and also
|
||||||
|
some variant of 'suexec' (or a proper setup php-fpm pool)
|
||||||
|
NOTE: mod_rewrite or its equivalent is extremely useful.
|
||||||
|
|
||||||
|
Your PHP installation must include the following PHP extensions for a
|
||||||
|
functional setup of GNU social:
|
||||||
|
|
||||||
|
openssl
|
||||||
|
(compiled in for Debian, enabled manually in Arch Linux)
|
||||||
|
|
||||||
|
php5-curl
|
||||||
|
Fetching files by HTTP.
|
||||||
|
|
||||||
|
php5-gd
|
||||||
|
Image manipulation (scaling).
|
||||||
|
|
||||||
|
php5-gmp
|
||||||
|
For Salmon signatures (part of OStatus).
|
||||||
|
|
||||||
|
php5-intl
|
||||||
|
Internationalization support (transliteration et al).
|
||||||
|
|
||||||
|
php5-json
|
||||||
|
For WebFinger lookups and more.
|
||||||
|
|
||||||
|
php5-mysqlnd
|
||||||
|
The native driver for PHP5 MariaDB connections. If you use MySQL,
|
||||||
|
``php5-mysql`` or ``php5-mysqli`` may be enough.
|
||||||
|
|
||||||
|
The above package names are for Debian based systems. In the case of Arch
|
||||||
|
Linux, PHP is compiled with support for most extensions but they require manual
|
||||||
|
enabling in the relevant ``php.ini`` file (mostly ``php5-gmp``).
|
||||||
|
|
||||||
|
Better performance
|
||||||
|
^^^^^^^^^^^^^^^^^^
|
||||||
|
For some functionality, you will also need the following extensions:
|
||||||
|
|
||||||
|
opcache
|
||||||
|
Improves performance a lot. Included in PHP, must be enabled manually in
|
||||||
|
``php.ini`` for most distributions. Find and set at least:
|
||||||
|
``opcache.enable=1``
|
||||||
|
|
||||||
|
mailparse
|
||||||
|
Efficient parsing of email requires this extension. Submission by email or
|
||||||
|
SMS-over-email uses this.
|
||||||
|
|
||||||
|
sphinx
|
||||||
|
A client for the sphinx server, an alternative to MySQL or Postgresql
|
||||||
|
fulltext search. You will also need a Sphinx server to serve the search
|
||||||
|
queries.
|
||||||
|
|
||||||
|
gettext
|
||||||
|
For multiple languages. Default on many PHP installs; will be emulated if not
|
||||||
|
present.
|
||||||
|
|
||||||
|
exif
|
||||||
|
For thumbnails to be properly oriented.
|
||||||
|
|
||||||
|
You may also experience better performance from your site if you configure a
|
||||||
|
PHP cache/accelerator. Most distributions come with "opcache" support. Enable
|
||||||
|
it in your ``php.ini`` where it is documented together with its settings.
|
||||||
|
|
||||||
|
|
||||||
|
Installation
|
||||||
|
------------
|
||||||
|
.. _getting-it-up-and-running:
|
||||||
|
|
||||||
|
Getting it up and running
|
||||||
|
^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||||
|
Installing the basic GNU Social web component is relatively easy, especially if
|
||||||
|
you've previously installed PHP/MariaDB packages.
|
||||||
|
|
||||||
|
1. The source code is distributed using a git repository `on GNU's Gitlab
|
||||||
|
server`_. There are two ways to download it:
|
||||||
|
|
||||||
|
* Use `git`_ on your own computer to clone the repository. Once it is
|
||||||
|
on your computer it is easy to download incremental updates.
|
||||||
|
|
||||||
|
* Download a zip or tarball from Gitlab's web interface. This way you won't
|
||||||
|
need git but you will need to download the whole thing every time you
|
||||||
|
update.
|
||||||
|
|
||||||
|
If you want to use git, run the following command. It will download the
|
||||||
|
whole repository and place it in a folder called gnusocial.
|
||||||
|
|
||||||
|
``git clone https://git.gnu.io/gnu/gnu-social.git gnusocial``
|
||||||
|
|
||||||
|
Then select the branch you wish to use::
|
||||||
|
|
||||||
|
cd gnusocial
|
||||||
|
git checkout master # or '1.2.x' or 'nightly'
|
||||||
|
|
||||||
|
If you would like to download it directly instead, go to the `1.2.x`_,
|
||||||
|
`master`_ or `nightly`_ branch on the Gitlab web page. In the top-right
|
||||||
|
corner there is a button to download a zip file containing that branch. If
|
||||||
|
you press the drop-down arrow on the right you can access different types of
|
||||||
|
archive.
|
||||||
|
|
||||||
|
.. todo:: code block the links
|
||||||
|
|
||||||
|
.. image:: ../../resources/admin/tree_download.png
|
||||||
|
:alt: Download button on gitlab
|
||||||
|
:align: center
|
||||||
|
|
||||||
|
.. _1.2.x: https://git.gnu.io/gnu/gnu-social/tree/1.2.x
|
||||||
|
.. _master: https://git.gnu.io/gnu/gnu-social/tree/master
|
||||||
|
.. _nightly: https://git.gnu.io/gnu/gnu-social/tree/nightly
|
||||||
|
|
||||||
|
Unpack the tarball you downloaded on your Web server. Usually a command like
|
||||||
|
this will work::
|
||||||
|
|
||||||
|
tar zxf gnu-social-*.tar.gz
|
||||||
|
|
||||||
|
...which will make a subdirectory in your current directory. (If you don't
|
||||||
|
have shell access on your Web server, you may have to unpack the tarball on
|
||||||
|
your local computer and FTP the files to the server.)
|
||||||
|
|
||||||
|
2. Whichever way you downloaded GNU social, move the files to a directory of
|
||||||
|
your choosing in your Web root directory. Usually something like this will
|
||||||
|
work:
|
||||||
|
|
||||||
|
For a git repository::
|
||||||
|
|
||||||
|
cd gnusocial
|
||||||
|
mkdir /var/www/gnusocial
|
||||||
|
cp -rv * /var/www/gnusocial
|
||||||
|
|
||||||
|
For a downloaded tarball::
|
||||||
|
|
||||||
|
mv gnu-social-x.y.z /var/www/gnusocial
|
||||||
|
|
||||||
|
This will often make your GNU Social instance available in the ``gnusocial``
|
||||||
|
path of your server, like ``http://example.net/gnusocial``. "social" or
|
||||||
|
"blog" might also be good path names. If you know how to configure virtual
|
||||||
|
hosts on your web server, you can try setting up
|
||||||
|
``http://social.example.net/`` or the like.
|
||||||
|
|
||||||
|
If you have "rewrite" support on your webserver, and you should, then please
|
||||||
|
enable this in order to make full use of your site. This will enable
|
||||||
|
:ref:`fancy-urls` support.
|
||||||
|
|
||||||
|
3. Make your target directory writeable by the Web server, please note however
|
||||||
|
that will give all users write access and securing the webserver is not
|
||||||
|
within the scope of this document. ::
|
||||||
|
|
||||||
|
chmod a+w /var/www/gnusocial/
|
||||||
|
|
||||||
|
On some systems, this will work as a more secure alternative::
|
||||||
|
|
||||||
|
chgrp www-data /var/www/gnusocial/
|
||||||
|
chmod g+w /var/www/gnusocial/
|
||||||
|
|
||||||
|
If your Web server runs as another user besides ``www-data``, try that user's
|
||||||
|
default group instead. As a last resort, you can create a new group like
|
||||||
|
``gnusocial`` and add the web server's user to the group.
|
||||||
|
|
||||||
|
4. You should also take this moment to make your ``avatar`` and ``file``
|
||||||
|
sub-directories writeable by the Web server. The insecure way to do this
|
||||||
|
is::
|
||||||
|
|
||||||
|
chmod a+w /var/www/gnusocial/avatar
|
||||||
|
chmod a+w /var/www/gnusocial/file
|
||||||
|
|
||||||
|
You can also make the avatar, and file directories just writable by the web
|
||||||
|
server group, as noted above.
|
||||||
|
|
||||||
|
5. Create a database to hold your site data. Something like this should work
|
||||||
|
(you will be prompted for your database password)::
|
||||||
|
|
||||||
|
mysqladmin -u "root" -p create socia
|
||||||
|
|
||||||
|
Note that GNU social should have its own database; you should not share the
|
||||||
|
database with another program. You can name it whatever you want, though.
|
||||||
|
|
||||||
|
(If you don't have shell access to your server, you may need to use a tool
|
||||||
|
like phpMyAdmin to create a database. Check your hosting service's
|
||||||
|
documentation for how to create a new MariaDB database.)
|
||||||
|
|
||||||
|
6. Create a new database account that GNU social will use to access the
|
||||||
|
database. If you have shell access, this will probably work from the MariaDB
|
||||||
|
shell::
|
||||||
|
|
||||||
|
GRANT ALL on social.*
|
||||||
|
TO 'social'@'localhost'
|
||||||
|
IDENTIFIED BY 'agoodpassword';
|
||||||
|
|
||||||
|
You should change the user identifier ``social`` and ``agoodpassword`` to
|
||||||
|
your preferred new database username and password. You may want to test
|
||||||
|
logging in to MariaDB as this new user.
|
||||||
|
|
||||||
|
7. In a browser, navigate to the GNU Social install script; something like::
|
||||||
|
|
||||||
|
https://social.example.net/install.php
|
||||||
|
|
||||||
|
Enter the database connection information and your site name. The install
|
||||||
|
program will configure your site and install the initial, almost-empty
|
||||||
|
database.
|
||||||
|
|
||||||
|
8. You should now be able to navigate to your social site's main directory and
|
||||||
|
see the "Public Timeline", which will probably be empty. You can now
|
||||||
|
register new users, post some notices, edit your profile, etc.
|
||||||
|
|
||||||
|
.. _fancy-urls:
|
||||||
|
|
||||||
|
Fancy URLs
|
||||||
|
^^^^^^^^^^
|
||||||
|
By default, GNU Social will use URLs that include the main PHP program's name
|
||||||
|
in them. For example, a user's home profile might be found at either of these
|
||||||
|
URLS depending on the webserver's configuration and capabilities::
|
||||||
|
|
||||||
|
https://social.example.net/index.php/fred
|
||||||
|
https://social.example.net/index.php?p=fred
|
||||||
|
|
||||||
|
It's possible to configure the software to use fancy URLs so it looks like this
|
||||||
|
instead::
|
||||||
|
|
||||||
|
https://social.example.net/fred
|
||||||
|
|
||||||
|
These "fancy URLs" are more readable and memorable for users. To use fancy
|
||||||
|
URLs, you must either have Apache 2.x with ``.htaccess`` enabled and
|
||||||
|
mod_rewrite enabled, OR know how to configure "url redirection" in your server
|
||||||
|
(like lighttpd or nginx).
|
||||||
|
|
||||||
|
1. See the instructions for each respective webserver software:
|
||||||
|
|
||||||
|
* For Apache, inspect the ``htaccess.sample`` file and save it as
|
||||||
|
``.htaccess`` after making any necessary modifications. Our sample file is
|
||||||
|
well commented.
|
||||||
|
|
||||||
|
* For lighttpd, inspect the lighttpd.conf.example file and apply the
|
||||||
|
appropriate changes in your virtualhost configuration for lighttpd.
|
||||||
|
|
||||||
|
* For nginx, inspect the ``nginx.conf.sample`` file and apply the appropriate
|
||||||
|
changes.
|
||||||
|
|
||||||
|
* For other webservers, we gladly accept contributions of server
|
||||||
|
configuration examples.
|
||||||
|
|
||||||
|
2. Assuming your webserver is properly configured and have its settings applied
|
||||||
|
(remember to reload/restart it), you can add this to your GNU social's
|
||||||
|
``config.php`` file::
|
||||||
|
|
||||||
|
$config['site']['fancy'] = true;
|
||||||
|
|
||||||
|
You should now be able to navigate to a "fancy" URL on your server, like::
|
||||||
|
|
||||||
|
https://social.example.net/main/register
|
||||||
|
|
||||||
|
Themes
|
||||||
|
^^^^^^
|
||||||
|
As of right now, your ability change the theme is limited to CSS stylesheets
|
||||||
|
and some image files; you can't change the HTML output, like adding or removing
|
||||||
|
menu items, without the help of a plugin.
|
||||||
|
|
||||||
|
You can choose a theme using the ``$config['site']['theme']`` element in the
|
||||||
|
``config.php`` file. See below for details.
|
||||||
|
|
||||||
|
You can add your own theme by making a sub-directory of the 'theme'
|
||||||
|
subdirectory with the name of your theme. Each theme can have the following
|
||||||
|
files:
|
||||||
|
|
||||||
|
display.css
|
||||||
|
a CSS2 file for "default" styling for all browsers.
|
||||||
|
|
||||||
|
logo.png
|
||||||
|
a logo image for the site.
|
||||||
|
|
||||||
|
default-avatar-profile.png
|
||||||
|
a 96x96 pixel image to use as the avatar for users who don't upload their
|
||||||
|
own.
|
||||||
|
|
||||||
|
default-avatar-stream.png
|
||||||
|
Ditto, but 48x48. For streams of notices.
|
||||||
|
|
||||||
|
default-avatar-mini.png
|
||||||
|
Ditto ditto, but 24x24. For subscriptions listing on profile pages.
|
||||||
|
|
||||||
|
You may want to start by copying the files from the default theme to your own
|
||||||
|
directory.
|
||||||
|
|
||||||
|
Private
|
||||||
|
^^^^^^^
|
||||||
|
A GNU social node can be configured as "private", which means it will not
|
||||||
|
federate with other nodes in the network. It is not a recommended method of
|
||||||
|
using GNU social and we cannot at the current state of development guarantee
|
||||||
|
that there are no leaks (what a public network sees as features, private sites
|
||||||
|
will likely see as bugs).
|
||||||
|
|
||||||
|
Private nodes are however an easy way to easily setup collaboration and image
|
||||||
|
sharing within a workgroup or a smaller community where federation is not a
|
||||||
|
desired feature. Also, it is possible to change this setting and instantly gain
|
||||||
|
full federation features.
|
||||||
|
|
||||||
|
Access to file attachments can also be restricted to logged-in users only:
|
||||||
|
|
||||||
|
1. Add a directory outside the web root where your file uploads will be stored.
|
||||||
|
Use this command as an initial guideline to create it::
|
||||||
|
|
||||||
|
mkdir /var/www/gnusocial-files
|
||||||
|
|
||||||
|
2. Make the file uploads directory writeable by the web server. An insecure way
|
||||||
|
to do this is (to do it properly, read up on UNIX file permissions and
|
||||||
|
configure your webserver accordingly)::
|
||||||
|
|
||||||
|
chmod a+x /var/www/gnusocial-files
|
||||||
|
|
||||||
|
3. Tell GNU social to use this directory for file uploads. Add a line like this
|
||||||
|
to your ``config.php``::
|
||||||
|
|
||||||
|
$config['attachments']['dir'] = '/var/www/gnusocial-files';
|
||||||
|
|
||||||
|
Extra features
|
||||||
|
--------------
|
||||||
|
|
||||||
|
Sphinx
|
||||||
|
^^^^^^
|
||||||
|
To use a Sphinx server to search users and notices, you'll need to enable the
|
||||||
|
SphinxSearch plugin. Add to your ``config.php``::
|
||||||
|
|
||||||
|
addPlugin('SphinxSearch');
|
||||||
|
$config['sphinx']['server'] = 'searchhost.local';
|
||||||
|
|
||||||
|
You also need to install, compile and enable the sphinx pecl extension for php
|
||||||
|
on the client side, which itself depends on the sphinx development files.
|
||||||
|
|
||||||
|
See ``plugins/SphinxSearch/README`` for more details and server setup.
|
||||||
|
|
||||||
|
SMS
|
||||||
|
^^^
|
||||||
|
StatusNet supports a cheap-and-dirty system for sending update messages to
|
||||||
|
mobile phones and for receiving updates from the mobile. Instead of sending
|
||||||
|
through the SMS network itself, which is costly and requires buy-in from the
|
||||||
|
wireless carriers, it simply piggybacks on the email gateways that many
|
||||||
|
carriers provide to their customers. So, SMS configuration is essentially email
|
||||||
|
configuration.
|
||||||
|
|
||||||
|
Each user sends to a made-up email address, which they keep a secret. Incoming
|
||||||
|
email that is "From" the user's SMS email address, and "To" the users' secret
|
||||||
|
email address on the site's domain, will be converted to a notice and stored in
|
||||||
|
the DB.
|
||||||
|
|
||||||
|
For this to work, there *must* be a domain or sub-domain for which all (or
|
||||||
|
most) incoming email can pass through the incoming mail filter.
|
||||||
|
|
||||||
|
1. Run the SQL script ``carrier.sql`` in your StatusNet database. This will
|
||||||
|
usually work::
|
||||||
|
|
||||||
|
mysql -u "statusnetuser" --password="statusnetpassword" statusnet < db/carrier.sql
|
||||||
|
|
||||||
|
This will populate your database with a list of wireless carriers that
|
||||||
|
support email SMS gateways.
|
||||||
|
|
||||||
|
2. Make sure the maildaemon.php file is executable::
|
||||||
|
|
||||||
|
chmod +x scripts/maildaemon.php
|
||||||
|
|
||||||
|
Note that "daemon" is kind of a misnomer here; the script is more of a filter
|
||||||
|
than a daemon.
|
||||||
|
|
||||||
|
3. Edit ``/etc/aliases`` on your mail server and add the following line::
|
||||||
|
|
||||||
|
*: /path/to/statusnet/scripts/maildaemon.php
|
||||||
|
|
||||||
|
4. Run whatever code you need to to update your aliases database. For many mail
|
||||||
|
servers (Postfix, Exim, Sendmail), this should work::
|
||||||
|
|
||||||
|
newaliases
|
||||||
|
|
||||||
|
You may need to restart your mail server for the new database to take effect.
|
||||||
|
|
||||||
|
5. Set the following in your ``config.php`` file::
|
||||||
|
|
||||||
|
$config['mail']['domain'] = 'yourdomain.example.net';
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
After installation
|
||||||
|
------------------
|
||||||
|
|
||||||
|
Run queue daemons
|
||||||
|
^^^^^^^^^^^^^^^^^
|
||||||
|
By default GNU social tries to do regular work such as communicating with
|
||||||
|
remote servers while it is handling HTTP requests for users. This is often
|
||||||
|
insufficient. If possible you should run the queue daemons. Please refer to
|
||||||
|
this section: :doc:`using_queue_daemons`.
|
||||||
|
|
||||||
|
.. todo:: remove italics from Using Queue Daemons link
|
||||||
|
|
||||||
|
Backups
|
||||||
|
^^^^^^^
|
||||||
|
There is no built-in system for doing backups in GNU social. You can make
|
||||||
|
backups of a working system by backing up the database and the Web directory.
|
||||||
|
To backup the database use `mysqldump`_ and to backup the Web directory, try
|
||||||
|
tar.
|
||||||
|
|
||||||
|
.. _mysqldump: https://mariadb.com/kb/en/mariadb/mysqldump/
|
||||||
|
|
||||||
|
Upgrading
|
||||||
|
^^^^^^^^^
|
||||||
|
Upgrading is strongly recommended to stay up to date with security fixes and
|
||||||
|
new features. For instructions on how to upgrade GNU social code, please refer
|
||||||
|
to this section: :doc:`upgrading_your_installation`.
|
||||||
|
|
||||||
|
.. todo:: remove italics from Upgrading Your Installation link
|
||||||
|
|
||||||
|
.. _Qvitter: https://git.gnu.io/h2p/Qvitter
|
||||||
|
.. _obtain a trusted certificate at no cost: https://letsencrypt.org/howitworks/
|
||||||
|
.. _on GNU's Gitlab server: https://git.gnu.io/gnu/gnu-social
|
||||||
|
.. _git: https://git-scm.com/
|
4
docs/admin/protocol_overview.rst
Normal file
4
docs/admin/protocol_overview.rst
Normal file
|
@ -0,0 +1,4 @@
|
||||||
|
Protocol Overview
|
||||||
|
=================
|
||||||
|
GNU social runs primarily on voodoo magic. If anybody knows better please
|
||||||
|
advise.
|
120
docs/admin/upgrading_your_installation.rst
Normal file
120
docs/admin/upgrading_your_installation.rst
Normal file
|
@ -0,0 +1,120 @@
|
||||||
|
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
|
||||||
|
|
103
docs/admin/using_queue_daemons.rst
Normal file
103
docs/admin/using_queue_daemons.rst
Normal file
|
@ -0,0 +1,103 @@
|
||||||
|
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
|
:maxdepth: 2
|
||||||
|
|
||||||
user/index
|
user/index
|
||||||
|
admin/index
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
|
Loading…
Reference in New Issue
Block a user