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:
John Kristensen
parent
3575fc337d
commit
49c0114104
|
|
@ -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
|
||||
|
|
@ -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
|
||||
|
|
@ -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
|
||||
|
|
@ -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/
|
||||
|
|
@ -0,0 +1,4 @@
|
|||
Protocol Overview
|
||||
=================
|
||||
GNU social runs primarily on voodoo magic. If anybody knows better please
|
||||
advise.
|
||||
|
|
@ -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
|
||||
|
||||
|
|
@ -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
|
||||
|
||||
user/index
|
||||
admin/index
|
||||
|
||||
|
||||
|
||||
|
|
|
|||
Loading…
Reference in New Issue