#5314 Prevent ZeroDivisionError in exif.py

[mediagoblin.git] / docs / source / siteadmin / deploying.rst

diff --git a/docs/source/siteadmin/deploying.rst b/docs/source/siteadmin/deploying.rst
index de4ce1acc3ac9ea671daaf89a536cf33aa886b82..c7b06be0e2426a562f51bca02e232d2d9c63785b 100644 (file)
--- a/docs/source/siteadmin/deploying.rst
+++ b/docs/source/siteadmin/deploying.rst
@@ -17,25 +17,37 @@
 Deploying MediaGoblin
 =====================
 
 Deploying MediaGoblin
 =====================
 

-GNU MediaGoblin is fairly new and so at the time of writing, there
-aren't easy package-manager-friendly methods to install MediaGoblin.
-However, doing a basic install isn't too complex in and of itself.
+GNU MediaGoblin is fairly new, and so at the time of writing there aren't
+easy package-manager-friendly methods to install it. However, doing a basic
+install isn't too complex in and of itself. Following this deployment guide
+will take you step-by-step through setting up your own instance of MediaGoblin.

 
 

-There's an almost infinite way to deploy things... for now, we'll keep
-it simple with some assumptions and use a setup that combines
-mediagoblin + virtualenv + fastcgi + nginx on a .deb or .rpm based
-GNU/Linux distro.
+Of course, when it comes to setting up web applications like MediaGoblin,
+there's an almost infinite way to deploy things, so for now, we'll keep it
+simple with some assumptions. We recommend a setup that combines MediaGoblin +
+virtualenv + fastcgi + nginx on a .deb- or .rpm-based GNU/Linux distro.
+
+Other deployment options (e.g., deploying on FreeBSD, Arch Linux, using
+Apache, etc.) are possible, though! If you'd prefer a different deployment
+approach, see our
+`Deployment wiki page <http://wiki.mediagoblin.org/Deployment>`_.

 
 .. note::
 
    These tools are for site administrators wanting to deploy a fresh
 
 .. note::
 
    These tools are for site administrators wanting to deploy a fresh

-   install.  If instead you want to join in as a contributor, see our
+   install.  If you want to join in as a contributor, see our

    `Hacking HOWTO <http://wiki.mediagoblin.org/HackingHowto>`_ instead.
 
    `Hacking HOWTO <http://wiki.mediagoblin.org/HackingHowto>`_ instead.
 

-   There are also many ways to install servers... for the sake of
-   simplicity, our instructions below describe installing with nginx.
-   For more recipes, including Apache, see
-   `our wiki <http://wiki.mediagoblin.org/Deployment>`_.
+.. note::
+
+    Throughout the documentation we use the ``sudo`` command to indicate that
+    an instruction requires elevated user privileges to run. You can issue
+    these commands as the ``root`` user if you prefer.
+    
+    If you need help configuring ``sudo``, see the
+    `Debian wiki <https://wiki.debian.org/sudo/>`_ or the
+    `Fedora Project wiki <https://fedoraproject.org/wiki/Configuring_Sudo/>`_. 
+

 
 Prepare System
 --------------
 
 Prepare System
 --------------


@@ -45,25 +57,26 @@ Dependencies
 
 MediaGoblin has the following core dependencies:
 
 
 MediaGoblin has the following core dependencies:
 

-- Python 2.6 or 2.7
+- Python 2.7

 - `python-lxml <http://lxml.de/>`_
 - `git <http://git-scm.com/>`_
 - `SQLite <http://www.sqlite.org/>`_/`PostgreSQL <http://www.postgresql.org/>`_
 - `Python Imaging Library <http://www.pythonware.com/products/pil/>`_  (PIL)
 - `virtualenv <http://www.virtualenv.org/>`_
 - `python-lxml <http://lxml.de/>`_
 - `git <http://git-scm.com/>`_
 - `SQLite <http://www.sqlite.org/>`_/`PostgreSQL <http://www.postgresql.org/>`_
 - `Python Imaging Library <http://www.pythonware.com/products/pil/>`_  (PIL)
 - `virtualenv <http://www.virtualenv.org/>`_

+- `nodejs <https://nodejs.org>`_

 
 On a DEB-based system (e.g Debian, gNewSense, Trisquel, Ubuntu, and
 derivatives) issue the following command::
 
     sudo apt-get install git-core python python-dev python-lxml \
 
 On a DEB-based system (e.g Debian, gNewSense, Trisquel, Ubuntu, and
 derivatives) issue the following command::
 
     sudo apt-get install git-core python python-dev python-lxml \

-        python-imaging python-virtualenv
+        python-imaging python-virtualenv npm nodejs-legacy automake

 
 On a RPM-based system (e.g. Fedora, RedHat, and derivatives) issue the
 following command::
 
 
 On a RPM-based system (e.g. Fedora, RedHat, and derivatives) issue the
 following command::
 

-    yum install python-paste-deploy python-paste-script \
+    sudo yum install python-paste-deploy python-paste-script \

         git-core python python-devel python-lxml python-imaging \
         git-core python python-devel python-lxml python-imaging \

-        python-virtualenv
+        python-virtualenv npm automake

 
 Configure PostgreSQL
 ~~~~~~~~~~~~~~~~~~~~
 
 Configure PostgreSQL
 ~~~~~~~~~~~~~~~~~~~~


@@ -77,35 +90,58 @@ Configure PostgreSQL
 
    If you don't want/need postgres, skip this section.
 
 
    If you don't want/need postgres, skip this section.
 

-These are the packages needed for Debian Wheezy (stable)::
+These are the packages needed for Debian Jessie (stable)::

 
     sudo apt-get install postgresql postgresql-client python-psycopg2
 
 
     sudo apt-get install postgresql postgresql-client python-psycopg2
 

+These are the packages needed for an RPM-based system::
+
+    sudo yum install postgresql postgresql-server python-psycopg2
+
+An rpm-based system also requires that you initialize the PostgresSQL database
+with this command. The following command is not needed on a Debian-based
+platform, however::
+
+    sudo /usr/bin/postgresql-setup initdb
+

 The installation process will create a new *system* user named ``postgres``,
 The installation process will create a new *system* user named ``postgres``,

-it will have privilegies sufficient to manage the database. We will create a
+which will have privilegies sufficient to manage the database. We will create a

 new database user with restricted privilegies and a new database owned by our
 restricted database user for our MediaGoblin instance.
 
 In this example, the database user will be ``mediagoblin`` and the database
 name will be ``mediagoblin`` too.
 
 new database user with restricted privilegies and a new database owned by our
 restricted database user for our MediaGoblin instance.
 
 In this example, the database user will be ``mediagoblin`` and the database
 name will be ``mediagoblin`` too.
 

-To create our new user, run::
+We'll add these entities by first switching to the *postgres* account::

 
 

-    sudo -u postgres createuser mediagoblin
+    sudo su - postgres

 
 

-then answer NO to *all* the questions::
+This will change your prompt to a shell prompt, such as *-bash-4.2$*. Enter
+the following *createuser* and *createdb* commands at that prompt. We'll
+create the *mediagoblin* database user first::

 
 

-    Shall the new role be a superuser? (y/n) n
-    Shall the new role be allowed to create databases? (y/n) n
-    Shall the new role be allowed to create more new roles? (y/n) n
+    # this command and the one that follows are run as the ``postgres`` user:
+    createuser -A -D mediagoblin

 
 

-then create the database all our MediaGoblin data should be stored in::
+Then we'll create the database where all of our MediaGoblin data will be stored::

 
 

-    sudo -u postgres createdb -E UNICODE -O mediagoblin mediagoblin
+    createdb -E UNICODE -O mediagoblin mediagoblin

 
 where the first ``mediagoblin`` is the database owner and the second
 ``mediagoblin`` is the database name.
 
 
 where the first ``mediagoblin`` is the database owner and the second
 ``mediagoblin`` is the database name.
 

+Type ``exit`` to exit from the 'postgres' user account.
+
+From here we just need to set the Postgres database to start on boot, and also
+start it up for this particular session. If you're on a platform that does not
+use *systemd*, you can enter::
+
+    sudo chkconfig postgresql on && service postgresql start
+
+Whereas users of *systemd*-based systems will need to enter::
+
+    sudo systemctl enable postgresql && systemctl start postgresql
+

 .. caution:: Where is the password?
 
     These steps enable you to authenticate to the database in a password-less
 .. caution:: Where is the password?
 
     These steps enable you to authenticate to the database in a password-less


@@ -122,8 +158,8 @@ Drop Privileges for MediaGoblin
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 MediaGoblin does not require special permissions or elevated
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 MediaGoblin does not require special permissions or elevated

-access to run. As such, the prefered way to run MediaGoblin is to 
-create a dedicated, unpriviledged system user for sole the purpose of running
+access to run. As such, the preferred way to run MediaGoblin is to
+create a dedicated, unprivileged system user for the sole purpose of running

 MediaGoblin. Running MediaGoblin processes under an unpriviledged system user
 helps to keep it more secure. 
 
 MediaGoblin. Running MediaGoblin processes under an unpriviledged system user
 helps to keep it more secure. 
 


@@ -131,28 +167,15 @@ The following command (entered as root or with sudo) will create a
 system account with a username of ``mediagoblin``. You may choose a different
 username if you wish.::
 
 system account with a username of ``mediagoblin``. You may choose a different
 username if you wish.::
 

-   adduser --system mediagoblin
+    sudo useradd -c "GNU MediaGoblin system account" -d /home/mediagoblin -U -m -r mediagoblin

 
 No password will be assigned to this account, and you will not be able
 
 No password will be assigned to this account, and you will not be able

-to log in as this user. To switch to this account, enter either::
-
-  sudo su - mediagoblin (if you have sudo permissions)
-
-or::
-
-  su - mediagoblin (if you have to use root permissions)
+to log in as this user. To switch to this account, enter::

 
 

-You may get a warning similar to this when entering these commands::
+    sudo su mediagoblin -s /bin/bash

 
 

-  warning: cannot change directory to /home/mediagoblin: No such file or directory
-
-You can disregard this warning. To return to your regular user account after
-using the system account, just enter ``exit``.
-
-.. note::
-
-    Unless otherwise noted, the remainder of this document assumes that all
-    operations are performed using this unpriviledged account.
+To return to your regular user account after using the system account, type
+``exit``.

 
 .. _create-mediagoblin-directory:
 
 
 .. _create-mediagoblin-directory:
 


@@ -171,62 +194,43 @@ to the unpriviledged system account.
 To do this, enter either of the following commands, changing the defaults
 to suit your particular requirements::
 
 To do this, enter either of the following commands, changing the defaults
 to suit your particular requirements::
 

-  sudo mkdir -p /srv/mediagoblin.example.org && sudo chown -hR mediagoblin:mediagoblin /srv/mediagobin.example.org
+    sudo mkdir -p /srv/mediagoblin.example.org && sudo chown -hR mediagoblin: /srv/mediagoblin.example.org

 
 

-or (as the root user)::
+.. note::

 
 

-  mkdir -p /srv/mediagoblin.example.org && chown -hR mediagoblin:mediagoblin /srv/mediagobin.example.org
+    Unless otherwise noted, the remainder of this document assumes that all
+    operations are performed using this unpriviledged account.

 
 
 Install MediaGoblin and Virtualenv
 ----------------------------------
 
 
 
 Install MediaGoblin and Virtualenv
 ----------------------------------
 

-.. note::
-
-   MediaGoblin is still developing rapidly. As a result
-   the following instructions recommend installing from the ``master``
-   branch of the git repository. Eventually production deployments will
-   want to transition to running from more consistent releases.
-
-We will now clone the MediaGoblin source code repository and setup and
-configure the necessary services. Modify these commands to
-suit your own environment. As a reminder, you should enter these
-commands using your unpriviledged system account.
+We will now switch to our 'mediagoblin' system account, and then set up
+our MediaGoblin source code repository and its necessary services.
+You should modify these commands to suit your own environment.

 
 Change to the MediaGoblin directory that you just created::
 
 
 Change to the MediaGoblin directory that you just created::
 

-    cd /srv/mediagoblin.example.org
+    sudo su mediagoblin -s /bin/bash  # to change to the 'mediagoblin' account
+    $ cd /srv/mediagoblin.example.org

 
 Clone the MediaGoblin repository and set up the git submodules::
 
 
 Clone the MediaGoblin repository and set up the git submodules::
 

-    git clone git://gitorious.org/mediagoblin/mediagoblin.git
-    cd mediagoblin
-    git submodule init && git submodule update
-
-
-And set up the in-package virtualenv::
-
-    (virtualenv --system-site-packages . || virtualenv .) && ./bin/python setup.py develop
+    $ git clone git://git.savannah.gnu.org/mediagoblin.git -b stable
+    $ cd mediagoblin
+    $ git submodule init && git submodule update

 
 .. note::
 
 
 .. note::
 

-   We presently have an experimental make-style deployment system.  if
-   you'd like to try it, instead of the above command, you can run::
+   The MediaGoblin repository used to be on gitorious.org, but since
+   gitorious.org shut down, we had to move.  We are presently on
+   Savannah.  You may need to update your git repository location::

 
 

-     ./bootstrap.sh && ./configure && make
+    $ git remote set-url origin git://git.savannah.gnu.org/mediagoblin.git

 
 

-   This also includes a number of nice features, such as keeping your
-   viratualenv up to date by simply running `make update`.
+Set up the hacking environment::

 
 

-.. ::
-
-   (NOTE: Is this still relevant?)
-
-   If you have problems here, consider trying to install virtualenv
-   with the ``--distribute`` or ``--no-site-packages`` options. If
-   your system's default Python is in the 3.x series you may need to
-   run ``virtualenv`` with the  ``--python=python2.7`` or
-   ``--python=python2.6`` options.
+    $ ./bootstrap.sh && ./configure && make

 
 The above provides an in-package install of ``virtualenv``. While this
 is counter to the conventional ``virtualenv`` configuration, it is
 
 The above provides an in-package install of ``virtualenv``. While this
 is counter to the conventional ``virtualenv`` configuration, it is


@@ -237,23 +241,20 @@ your preferred method.
 Assuming you are going to deploy with FastCGI, you should also install
 flup::
 
 Assuming you are going to deploy with FastCGI, you should also install
 flup::
 

-    ./bin/easy_install flup
-
-(Sometimes this breaks because flup's site is flakey.  If it does for
-you, try)::
-
-    ./bin/easy_install https://pypi.python.org/pypi/flup/1.0.3.dev-20110405
+    $ ./bin/easy_install flup

 
 This concludes the initial configuration of the development
 environment. In the future, when you update your
 codebase, you should also run::
 
 
 This concludes the initial configuration of the development
 environment. In the future, when you update your
 codebase, you should also run::
 

-    ./bin/python setup.py develop --upgrade && ./bin/gmg dbupdate && git submodule fetch
+    $ git submodule update && ./bin/python setup.py develop --upgrade && ./bin/gmg dbupdate
+
+.. note::

 
 

-Note: If you are running an active site, depending on your server
-configuration, you may need to stop it first or the dbupdate command
-may hang (and it's certainly a good idea to restart it after the
-update)
+    Note: If you are running an active site, depending on your server
+    configuration, you may need to stop it first or the dbupdate command
+    may hang (and it's certainly a good idea to restart it after the
+    update)

 
 
 Deploy MediaGoblin Services
 
 
 Deploy MediaGoblin Services


@@ -266,7 +267,7 @@ A few basic properties must be set before MediaGoblin will work. First
 make a copy of ``mediagoblin.ini`` for editing so the original config
 file isn't lost::
 
 make a copy of ``mediagoblin.ini`` for editing so the original config
 file isn't lost::
 

-    cp mediagoblin.ini mediagoblin_local.ini
+    $ cp mediagoblin.ini mediagoblin_local.ini

 
 Then:
  - Set ``email_sender_address`` to the address you wish to be used as
 
 Then:
  - Set ``email_sender_address`` to the address you wish to be used as


@@ -293,7 +294,7 @@ Update database data structures
 
 Before you start using the database, you need to run::
 
 
 Before you start using the database, you need to run::
 

-    ./bin/gmg dbupdate
+    $ ./bin/gmg dbupdate

 
 to populate the database with the MediaGoblin data structures.
 
 
 to populate the database with the MediaGoblin data structures.
 


@@ -304,7 +305,7 @@ Test the Server
 At this point MediaGoblin should be properly installed.  You can
 test the deployment with the following command::
 
 At this point MediaGoblin should be properly installed.  You can
 test the deployment with the following command::
 

-    ./lazyserver.sh --server-name=broadcast
+    $ ./lazyserver.sh --server-name=broadcast

 
 You should be able to connect to the machine on port 6543 in your
 browser to confirm that the service is operable.
 
 You should be able to connect to the machine on port 6543 in your
 browser to confirm that the service is operable.


@@ -327,8 +328,8 @@ into a directory that will be included in your ``nginx`` configuration
 (e.g. "``/etc/nginx/sites-enabled`` or ``/etc/nginx/conf.d``) with
 one of the following commands (as the root user)::
 
 (e.g. "``/etc/nginx/sites-enabled`` or ``/etc/nginx/conf.d``) with
 one of the following commands (as the root user)::
 

-    ln -s /srv/mediagoblin.example.org/nginx.conf /etc/nginx/conf.d/
-    ln -s /srv/mediagoblin.example.org/nginx.conf /etc/nginx/sites-enabled/
+    sudo ln -s /srv/mediagoblin.example.org/nginx.conf /etc/nginx/conf.d/
+    sudo ln -s /srv/mediagoblin.example.org/nginx.conf /etc/nginx/sites-enabled/

 
 Modify these commands and locations depending on your preferences and
 the existing configuration of your nginx instance. The contents of
 
 Modify these commands and locations depending on your preferences and
 the existing configuration of your nginx instance. The contents of


@@ -398,13 +399,26 @@ this ``nginx.conf`` file should be modeled on the following::
      }
     }
 
      }
     }
 

+The first four ``location`` directives instruct Nginx to serve the
+static and uploaded files directly rather than through the MediaGoblin
+process. This approach is faster and requires less memory.
+
+.. note::
+
+   The user who owns the Nginx process, normally ``www-data``,
+   requires execute permission on the directories ``static``,
+   ``public``, ``theme_static`` and ``plugin_static`` plus all their
+   parent directories. This user also requires read permission on all
+   the files within these directories. This is normally the default.
+

 Now, nginx instance is configured to serve the MediaGoblin
 application. Perform a quick test to ensure that this configuration
 works. Restart nginx so it picks up your changes, with a command that
 Now, nginx instance is configured to serve the MediaGoblin
 application. Perform a quick test to ensure that this configuration
 works. Restart nginx so it picks up your changes, with a command that

-resembles one of the following (as the root user)::
+resembles one of the following::

 
     sudo /etc/init.d/nginx restart
     sudo /etc/rc.d/nginx restart
 
     sudo /etc/init.d/nginx restart
     sudo /etc/rc.d/nginx restart

+    sudo systemctl restart nginx

 
 Now start MediaGoblin. Use the following command sequence as an
 example::
 
 Now start MediaGoblin. Use the following command sequence as an
 example::


@@ -443,3 +457,7 @@ Security Considerations
    and restart the server, so that it creates a new secret key.
    All previous sessions will be invalidated.
 
    and restart the server, so that it creates a new secret key.
    All previous sessions will be invalidated.
 

+..
+   Local variables:
+   fill-column: 70
+   End: