docs: editing/tweaking deployment documentation
This commit is contained in:
parent
2f9bd4d458
commit
4e893b6ea1
@ -1,8 +1,6 @@
|
|||||||
.. _deployment-chapter:
|
=====================
|
||||||
|
Deploying MediaGoblin
|
||||||
=======================
|
=====================
|
||||||
Deploying MediaGoblin
|
|
||||||
=======================
|
|
||||||
|
|
||||||
GNU MediaGoblin is fairly new and so at the time of writing, there
|
GNU MediaGoblin is fairly new and so at the time of writing, there
|
||||||
aren't easy package-manager-friendly methods to install MediaGoblin.
|
aren't easy package-manager-friendly methods to install MediaGoblin.
|
||||||
@ -17,149 +15,167 @@ Note: these tools are for administrators wanting to deploy a fresh
|
|||||||
install. If instead you want to join in as a contributor, see our
|
install. If instead 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.
|
||||||
|
|
||||||
Install dependencies
|
Prepare System
|
||||||
====================
|
--------------
|
||||||
|
|
||||||
First thing you want to do is install necessary dependencies. Those
|
Dependencies
|
||||||
are, roughly:
|
~~~~~~~~~~~~
|
||||||
|
|
||||||
- Python 2.6 or 2.7
|
MediaGoblin has the following core dependencies:
|
||||||
- python-lxml - http://lxml.de/
|
|
||||||
- git - http://git-scm.com/
|
|
||||||
- MongoDB - http://www.mongodb.org/
|
|
||||||
- Python Imaging Library (PIL) - http://www.pythonware.com/products/pil/
|
|
||||||
- virtualenv - http://www.virtualenv.org/
|
|
||||||
|
|
||||||
On a .deb based system (Debian, GnewSense, Trisquel, Ubuntu, etc) run
|
- Python 2.6 or 2.7
|
||||||
the following:
|
- `python-lxml <http://lxml.de/>`_
|
||||||
|
- `git <http://git-scm.com/>`_
|
||||||
|
- `MongoDB <http://www.mongodb.org/>`_
|
||||||
|
- `Python Imaging Library <http://www.pythonware.com/products/pil/>`_ (PIL)
|
||||||
|
- `virtualenv <http://www.virtualenv.org/>`_
|
||||||
|
|
||||||
sudo apt-get install mongodb git-core python python-dev \
|
On a DEB-based system (e.g Debian, gNewSense, Trisquel, Ubuntu, and
|
||||||
python-lxml python-imaging python-virtualenv
|
derivatives) issue the following command: ::
|
||||||
|
|
||||||
On a .rpm based system (Fedora, RedHat, etc):
|
sudo apt-get install mongodb git-core python python-dev python-lxml python-imaging python-virtualenv
|
||||||
|
|
||||||
yum install mongodb-server python-paste-deploy python-paste-script \
|
On a RPM-based system (e.g. Fedora, RedHat, and derivatives) issue the
|
||||||
git-core python python-devel python-lxml python-imaging python-virtualenv
|
following command: ::
|
||||||
|
|
||||||
|
yum install mongodb-server python-paste-deploy python-paste-script git-core python python-devel python-lxml python-imaging python-virtualenv
|
||||||
|
|
||||||
Configure MongoDB
|
Configure MongoDB
|
||||||
=================
|
~~~~~~~~~~~~~~~~~
|
||||||
|
|
||||||
So you have MongoDB installed... you should probably make sure that
|
After installing MongoDB some preliminary database configuration may
|
||||||
you have a few things configured before you start up MediaGoblin.
|
be necessary.
|
||||||
|
|
||||||
For one thing, you almost certainly want to make sure `journaling
|
Ensure that MongoDB `journaling <http://www.mongodb.org/display/DOCS/Journaling>`_
|
||||||
<http://www.mongodb.org/display/DOCS/Journaling>`_ is enabled.
|
is enabled. Journaling is enabled by default in version 2.0 and later
|
||||||
Journaling is automatically enabled on 64 bit systems post-MongoDB
|
64-bit MongoDB instances. Check your deployment, and consider enabling
|
||||||
2.0, but you should check. (Not turning on journaling means that if
|
journaling if you're running 32-bit systems or earlier version.
|
||||||
your server crashes you have a good chance of losing data!)
|
|
||||||
|
.. warning::
|
||||||
|
|
||||||
|
Running MongoDB without journaling risks general data corruption
|
||||||
|
and raises the possibility of losing data within a 60-second
|
||||||
|
window when the server restarts.
|
||||||
|
|
||||||
|
MediaGoblin recommends enabling MongoDB's journaling feature by
|
||||||
|
adding a ``--journal`` flag to the command line or a "``journal:
|
||||||
|
true``" option to the configuration file.
|
||||||
|
|
||||||
MongoDB can take a lot of space by default. If you're planning on
|
MongoDB can take a lot of space by default. If you're planning on
|
||||||
running a smaller instance, consider following our `scaling down
|
running a smaller instance, consider the `scaling down guide
|
||||||
<http://wiki.mediagoblin.org/Scaling_Down>`_ guide (keeping in mind
|
<http://wiki.mediagoblin.org/Scaling_Down>`_ for some appropriate
|
||||||
that the steps recommended here are tradeoffs!).
|
tradeoffs to conserve space.
|
||||||
|
|
||||||
|
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.
|
||||||
|
|
||||||
|
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.
|
||||||
|
|
||||||
|
This document assumes that all operations are performed as this
|
||||||
|
user. To drop privileges to this user, run the following command: ::
|
||||||
|
|
||||||
|
|
||||||
Decide on a non-privileged user
|
su - [mediagoblin]``
|
||||||
===============================
|
|
||||||
|
|
||||||
As MediaGoblin does not require any special permissions, you
|
|
||||||
should either decide on a user to run it as, or even better create a
|
|
||||||
dedicated user for it. Consult your distribution's documentation on
|
|
||||||
how to create dedicated service user. Make sure it does have a locked
|
|
||||||
password, so nobody can login using this user.
|
|
||||||
|
|
||||||
You should create a working dir for MediaGoblin. We assume you will
|
|
||||||
check things out into /srv/mediagoblin.example.org/mediagoblin/ for
|
|
||||||
this documentation, but you can choose whatever fits your local needs.
|
|
||||||
|
|
||||||
Most of the remaining documentation assumes you're working as that
|
|
||||||
user. As root, you might want to do "su - mediagoblinuser".
|
|
||||||
|
|
||||||
|
Where, "``[mediagoblin]`` is the username of the system user that will
|
||||||
|
run MediaGoblin.
|
||||||
|
|
||||||
Install MediaGoblin and Virtualenv
|
Install MediaGoblin and Virtualenv
|
||||||
==================================
|
----------------------------------
|
||||||
|
|
||||||
For the moment, let's assume you want to run the absolute most
|
As of |version|, MediaGoblin has a rapid development pace. As a result
|
||||||
bleeding edge version of mediagoblin in mediagoblin master (possibly
|
the following instructions recommend installing from the ``master``
|
||||||
not the best choice in a production environment, so these docs should
|
branch of the git repository. Eventually production deployments will
|
||||||
be fixed ;)).
|
want to transition to running from more consistent releases.
|
||||||
|
|
||||||
Change to (and possibly make) the appropriate parent directory:
|
Issue the following commands, to create and change the working
|
||||||
|
directory. Modify these commands to reflect your own environment: ::
|
||||||
|
|
||||||
|
mkdir -p /srv/mediagoblin.example.org/
|
||||||
cd /srv/mediagoblin.example.org/
|
cd /srv/mediagoblin.example.org/
|
||||||
|
|
||||||
Clone the repository:
|
Clone the MediaGoblin repository: ::
|
||||||
|
|
||||||
git clone git://gitorious.org/mediagoblin/mediagoblin.git
|
git clone git://gitorious.org/mediagoblin/mediagoblin.git
|
||||||
|
|
||||||
And setup the in-package virtualenv:
|
And setup the in-package virtualenv: ::
|
||||||
|
|
||||||
cd mediagoblin
|
cd mediagoblin
|
||||||
virtualenv . && ./bin/python setup.py develop
|
virtualenv . && ./bin/python setup.py develop
|
||||||
|
|
||||||
(If you have problems here, consider trying to install virtualenv with
|
.. note::
|
||||||
one of the flags --distribute or --no-site-packages... Additionally if
|
|
||||||
your system has python3.X as the default you might need to do
|
|
||||||
virtualenv --python=python2.7 or --python=python2.6)
|
|
||||||
|
|
||||||
(You might note that we've done an in-package install of
|
If you have problems here, consider trying to install virtualenv
|
||||||
virtualenv... this isn't the most traditional way to install
|
with the ``--distribute`` or ``--no-site-packages`` options. If
|
||||||
virtualenv, and it might not even be the best. But it's the easiest
|
your system's default Python is in the 3.x series you man need to
|
||||||
to explain without having to explain python packaging, and it works.)
|
run ``virtualenv`` with the ``--python=python2.7`` or
|
||||||
|
``--python=python2.6`` options.
|
||||||
|
|
||||||
At this point your development environment should be setup. You don't
|
The above provides an in-package install of ``virtualenv``. While this
|
||||||
need to do anything else. However if at any point you update your
|
is counter to the conventional ``virtualenv`` configuration, it is
|
||||||
codebase, you should also run:
|
more reliable and considerably easier to configure and illustrate. If
|
||||||
|
you're familiar with Python packaging you may consider deploying with
|
||||||
|
your preferred the method.
|
||||||
|
|
||||||
|
This concludes the initial configuration of the development
|
||||||
|
environment. In the future, if at any point you want update your
|
||||||
|
codebase, you should also run: ::
|
||||||
|
|
||||||
./bin/python setup.py develop --upgrade && ./bin/gmg migrate.
|
./bin/python setup.py develop --upgrade && ./bin/gmg migrate.
|
||||||
|
|
||||||
|
Deploy MediaGoblin Services
|
||||||
|
---------------------------
|
||||||
|
|
||||||
Test-start the server
|
Test the Server
|
||||||
=====================
|
~~~~~~~~~~~~~~~
|
||||||
|
|
||||||
At this point mediagoblin should be properly installed. You can
|
At this point MediaGoblin should be properly installed. You can
|
||||||
test-start it like so:
|
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
|
You should be able to connect to the machine on port 6543 in your
|
||||||
browser to ensure that things are working.
|
browser to confirm that the service is operable.
|
||||||
|
|
||||||
|
Connect the Webserver to MediaGoblin with FastCGI
|
||||||
Hook up to your webserver via fastcgi
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||||
=====================================
|
|
||||||
|
|
||||||
This section describes how to configure MediaGoblin to work via
|
This section describes how to configure MediaGoblin to work via
|
||||||
fastcgi. Our configuration example will use nginx, as the author of
|
fastcgi. Our configuration example will use nginx, however, you may
|
||||||
this manual feels that nginx config files are easier to understand if
|
use any webserver of your choice as long as it supports the FastCGI
|
||||||
you have no experience with any type of configuration file. However,
|
protocol. If you do not already have a web server, consider nginx, as
|
||||||
the translations to apache are not too hard.
|
the configuration files may be more clear than the
|
||||||
|
alternatives.
|
||||||
|
|
||||||
Also for the sake of this document, we'll assume you're running
|
Create a configuration file at
|
||||||
mediagoblin on the domain mediagoblin.example.org and your
|
``/srv/mediagoblin.example.org/nginx.conf`` and create a symbolic link
|
||||||
mediagoblin checkout in /srv/mediagoblin.example.org/mediagoblin/
|
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:) ::
|
||||||
|
|
||||||
Now in reality, you won't be running mediagoblin on such a domain or
|
ln -s /srv/mediagoblin.example.org/nginx.conf /etc/nginx/conf.d/
|
||||||
in such a directory, but it should be easy enough to move your stuff
|
ln -s /srv/mediagoblin.example.org/nginx.conf /etc/nginx/sites-enabled/
|
||||||
over.
|
|
||||||
|
|
||||||
Anyway, in such an environment, make a config file in the normal place
|
Modify these commands and locations depending on your preferences and
|
||||||
you'd make such an nginx config file... probably
|
the existing configuration of your nginx instance. The contents of
|
||||||
/etc/nginx/sites-available/mediagoblin.example.conf (and symlink said
|
this ``nginx.conf`` file should be modeled on the following: ::
|
||||||
file over to /etc/nginx/sites-enabled/ to turn it on)
|
|
||||||
|
|
||||||
Now put in that file:
|
|
||||||
|
|
||||||
server {
|
server {
|
||||||
#################################################
|
#################################################
|
||||||
# Stock useful config options, but ignore them :)
|
# Stock useful config options, but ignore them :)
|
||||||
#################################################
|
#################################################
|
||||||
server_name mediagoblin.example.org www.mediagoblin.example.org;
|
|
||||||
include /etc/nginx/mime.types;
|
include /etc/nginx/mime.types;
|
||||||
|
|
||||||
access_log /var/log/nginx/mediagoblin.example.access.log;
|
|
||||||
error_log /var/log/nginx/mediagoblin.example.error.log;
|
|
||||||
|
|
||||||
autoindex off;
|
autoindex off;
|
||||||
default_type application/octet-stream;
|
default_type application/octet-stream;
|
||||||
sendfile on;
|
sendfile on;
|
||||||
@ -175,6 +191,10 @@ Now put in that file:
|
|||||||
# This is the section you should read
|
# This is the section you should read
|
||||||
#####################################
|
#####################################
|
||||||
|
|
||||||
|
server_name mediagoblin.example.org www.mediagoblin.example.org;
|
||||||
|
access_log /var/log/nginx/mediagoblin.example.access.log;
|
||||||
|
error_log /var/log/nginx/mediagoblin.example.error.log;
|
||||||
|
|
||||||
# MediaGoblin's stock static files: CSS, JS, etc.
|
# MediaGoblin's stock static files: CSS, JS, etc.
|
||||||
location /mgoblin_static/ {
|
location /mgoblin_static/ {
|
||||||
alias /srv/mediagoblin.example.org/mediagoblin/static/;
|
alias /srv/mediagoblin.example.org/mediagoblin/static/;
|
||||||
@ -192,31 +212,32 @@ Now put in that file:
|
|||||||
}
|
}
|
||||||
}
|
}
|
||||||
|
|
||||||
At this point your config file should be properly set up to handle
|
Now, nginx instance is configured to serve the MediaGoblin
|
||||||
serving mediagoblin. Now all you need to do is run it!
|
application. Perform a quick test to ensure that this configuration
|
||||||
|
works. Restart nginx so it picks up your changes, with a command that
|
||||||
Let's do a quick test. Restart nginx so it picks up your changes,
|
resembles one of the following (as the root user:) ::
|
||||||
something probably like:
|
|
||||||
|
|
||||||
sudo /etc/init.d/nginx restart
|
sudo /etc/init.d/nginx restart
|
||||||
|
sudo /etc/rc.d/nginx restart
|
||||||
|
|
||||||
Now start up MediaGoblin. "cd" to the MediaGoblin checkout and run:
|
Now start MediaGoblin. Use the following command sequence as an
|
||||||
|
example: ::
|
||||||
|
|
||||||
|
cd /srv/mediagoblin.example.org/mediagoblin/
|
||||||
./lazyserver.sh --server-name=fcgi fcgi_host=127.0.0.1 fcgi_port=26543
|
./lazyserver.sh --server-name=fcgi fcgi_host=127.0.0.1 fcgi_port=26543
|
||||||
|
|
||||||
Visit the site you've set up in your browser, eg
|
Visit the site you've set up in your browser by visiting
|
||||||
http://example.mediagoblin.org (except with the real domain name or IP
|
<http://mediagobilin.example.org>. You should see MediaGoblin!
|
||||||
you're expecting to use. ;))
|
|
||||||
|
|
||||||
|
Production MediaGoblin Deployments with Paste
|
||||||
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||||
|
|
||||||
A more permanent mediagoblin process via paste
|
The instance configured with ``lazyserver`` is not ideal for a
|
||||||
==============================================
|
production MediaGoblin deployment. Ideally, you should be able to use
|
||||||
|
a a control script (i.e. init script.) to launch and restart the
|
||||||
|
MediaGoblin process.
|
||||||
|
|
||||||
At this point, you probably have a MediaGoblin instance that for most
|
Use the following command as the basis for such a script: ::
|
||||||
intents and purposes works, but lazyserver is... well, lazy. You
|
|
||||||
probably want to set up a process that you can launch in init scripts.
|
|
||||||
|
|
||||||
Try something along the lines of:
|
|
||||||
|
|
||||||
CELERY_ALWAYS_EAGER=true \
|
CELERY_ALWAYS_EAGER=true \
|
||||||
/srv/mediagoblin.example.org/mediagoblin/bin/paster serve \
|
/srv/mediagoblin.example.org/mediagoblin/bin/paster serve \
|
||||||
@ -224,9 +245,10 @@ Try something along the lines of:
|
|||||||
--pid-file=/tmp/mediagoblin.pid \
|
--pid-file=/tmp/mediagoblin.pid \
|
||||||
--server-name=fcgi fcgi_host=127.0.0.1 fcgi_port=26543 \
|
--server-name=fcgi fcgi_host=127.0.0.1 fcgi_port=26543 \
|
||||||
|
|
||||||
Feel free to adjust any of this.
|
.. note::
|
||||||
|
|
||||||
Note that this runs MediaGoblin in "always eager" mode with Celery.
|
The above configuration places MediaGoblin in "always eager" mode
|
||||||
This is fine for development and smaller deployments. However if
|
with Celery. This is fine for development and smaller
|
||||||
you're getting into the really large deployment category, consider
|
deployments. However, if you're getting into the really large
|
||||||
reading the section of this manual on Celery.
|
deployment category, consider reading the section of this manual on
|
||||||
|
Celery.
|
||||||
|
Loading…
x
Reference in New Issue
Block a user