.. MediaGoblin Documentation
- Written in 2011, 2012 by MediaGoblin contributors
+ Written in 2011, 2012, 2013 by MediaGoblin contributors
To the extent possible under law, the author(s) have dedicated all
copyright and related and neighboring rights to this software to
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
+ # apt-get install git-core python python-dev python-lxml \
+ python-imaging python-virtualenv npm automake
On a RPM-based system (e.g. Fedora, RedHat, and derivatives) issue the
following command::
- yum install python-paste-deploy python-paste-script \
+ # 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 (testing)::
+These are the packages needed for Debian Wheezy (stable)::
- sudo apt-get install postgresql postgresql-client python-psycopg2
+ # apt-get install postgresql postgresql-client python-psycopg2
+
+These are the packages needed for an RPM-based system::
+
+ # 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::
+
+ # /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
+ # su -u 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
+ $ 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 return to the *root* user prompt. 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::
+
+ # chkconfig postgresql on && service postgresql start
+
+Whereas users of *systemd*-based systems will need to enter::
+
+ # systemctl enable postgresql && systemctl start postgresql
+
.. caution:: Where is the password?
These steps enable you to authenticate to the database in a password-less
Drop Privileges for MediaGoblin
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-As MediaGoblin does not require special permissions or elevated
-access, you should run MediaGoblin under an existing non-root user or
-preferably create a dedicated user for the purpose of running
-MediaGoblin. Consult your distribution's documentation on how to
-create "system account" or dedicated service user. Ensure that it is
-not possible to log in to your system with as this user.
+MediaGoblin does not require special permissions or elevated
+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.
+
+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.::
+
+ # useradd --system --user-group 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::
+
+ su mediagoblin -s /bin/bash # (if you have to use root permissions)
+
+You may get a warning similar to this when entering these commands::
+
+ 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``.
+
+.. _create-mediagoblin-directory:
+
+Create a MediaGoblin Directory
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
You should create a working directory for MediaGoblin. This document
assumes your local git repository will be located at
-``/srv/mediagoblin.example.org/mediagoblin/`` for this documentation.
-Substitute your prefer ed local deployment path as needed.
+``/srv/mediagoblin.example.org/mediagoblin/``.
+Substitute your prefered local deployment path as needed.
-This document assumes that all operations are performed as this
-user. To drop privileges to this user, run the following command::
+Setting up the working directory requires that we first create the directory
+with elevated priviledges, and then assign ownership of the directory
+to the unpriviledged system account.
- su - [mediagoblin]
+To do this, enter either of the following commands, changing the defaults
+to suit your particular requirements::
+
+ # mkdir -p /srv/mediagoblin.example.org && sudo chown -hR mediagoblin: /srv/mediagoblin.example.org
+
+.. note::
+
+ Unless otherwise noted, the remainder of this document assumes that all
+ operations are performed using this unpriviledged account.
-Where, "``[mediagoblin]``" is the username of the system user that will
-run MediaGoblin.
Install MediaGoblin and Virtualenv
----------------------------------
+We will now clone the MediaGoblin source code repository and setup and
+configure the necessary services. Modify these commands to
+suit your own environment.
+
.. 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.
+ As a reminder, you should enter these commands using your unpriviledged
+ *mediagoblin* system account.
-Issue the following commands, to create and change the working
-directory. Modify these commands to reflect your own environment::
+Change to the MediaGoblin directory that you just created::
- mkdir -p /srv/mediagoblin.example.org/
- cd /srv/mediagoblin.example.org/
+ $ 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::
+ $ git clone https://gitorious.org/mediagoblin/mediagoblin.git -b stable
+ $ cd mediagoblin
+ $ git submodule init && git submodule update
- (virtualenv --system-site-packages . || virtualenv .) && ./bin/python setup.py develop
-.. note::
+Set up the hacking environment::
- 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
}
}
+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
for session security. Make sure not to leak its contents anywhere.
If the contents gets leaked nevertheless, delete your file
and restart the server, so that it creates a new secret key.
- All previous sessions will be invalifated then.
+ All previous sessions will be invalidated.
+
+..
+ Local variables:
+ fill-column: 70
+ End: