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
- 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.
- 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
--------------
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/>`_
+- `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 \
- 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::
- 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 \
- python-virtualenv
+ python-virtualenv npm automake
Configure PostgreSQL
~~~~~~~~~~~~~~~~~~~~
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
+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``,
-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.
-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.
+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
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
-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:
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/mediagoblin.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/mediagoblin.example.org
+ Unless otherwise noted, the remainder of this document assumes that all
+ operations are performed using this unpriviledged account.
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::
- 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::
- 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::
- 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
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::
- ./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
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
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.
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.
(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
}
}
+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
-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 systemctl restart nginx
Now start MediaGoblin. Use the following command sequence as an
example::
and restart the server, so that it creates a new secret key.
All previous sessions will be invalidated.
+..
+ Local variables:
+ fill-column: 70
+ End: