X-Git-Url: https://vcs.fsf.org/?a=blobdiff_plain;f=docs%2Fsource%2Fsiteadmin%2Fdeploying.rst;h=13429fc44f6a0fe4d961a2d3175ed5778229b332;hb=5b8e0b2a63194d53da2ce434e867fc5eab1b60b4;hp=9bcc06371acef2d393122c6983a88383d8684be1;hpb=e02b7b6b3bd6b20c65aeb2ca5fd1e0030b631b88;p=mediagoblin.git diff --git a/docs/source/siteadmin/deploying.rst b/docs/source/siteadmin/deploying.rst index 9bcc0637..13429fc4 100644 --- a/docs/source/siteadmin/deploying.rst +++ b/docs/source/siteadmin/deploying.rst @@ -1,6 +1,6 @@ .. 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 @@ -17,25 +17,37 @@ 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 `_. .. 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 `_ 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 `_. +.. 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 `_ or the + `Fedora Project wiki `_. + Prepare System -------------- @@ -45,25 +57,27 @@ Dependencies MediaGoblin has the following core dependencies: -- Python 2.6 or 2.7 +- Python 2.7 - `python-lxml `_ - `git `_ - `SQLite `_/`PostgreSQL `_ - `Python Imaging Library `_ (PIL) - `virtualenv `_ +- `nodejs `_ 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 \ + nginx 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 nginx Configure PostgreSQL ~~~~~~~~~~~~~~~~~~~~ @@ -77,35 +91,52 @@ 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 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 and start the +PostgresSQL database with a few commands. The following commands are +not needed on a Debian-based platform, however:: + + sudo /usr/bin/postgresql-setup initdb + sudo systemctl enable postgresql + sudo systemctl start postgresql + 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.:: + + exit + .. caution:: Where is the password? These steps enable you to authenticate to the database in a password-less @@ -121,58 +152,99 @@ where the first ``mediagoblin`` is the database owner and the second 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. + +If you are using a Debian-based system, enter this command:: + + sudo useradd -c "GNU MediaGoblin system account" -d /var/lib/mediagoblin -m -r -g www-data mediagoblin + +If you are using an RPM-based system, enter this command:: + + sudo useradd -c "GNU MediaGoblin system account" -d /var/lib/mediagoblin -m -r -g nginx mediagoblin + +This will create a ``mediagoblin`` user and assign it to a group that is +associated with the web server. This will ensure that the web server can +read the media files (images, videos, etc.) that users upload. + +We will also create a ``mediagoblin`` group and associate the mediagoblin +user with that group, as well:: + + sudo groupadd mediagoblin && sudo usermod --append -G mediagoblin 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:: + + sudo su mediagoblin -s /bin/bash + +To return to your regular user account after using the system account, type +``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 the following command, changing the defaults to suit your +particular requirements. On a Debian-based platform you will enter this:: -Where, "``[mediagoblin]``" is the username of the system user that will -run MediaGoblin. + sudo mkdir -p /srv/mediagoblin.example.org && sudo chown -hR mediagoblin:www-data /srv/mediagoblin.example.org -Install MediaGoblin and Virtualenv ----------------------------------- +On an RPM-based distribution, enter this command:: + + sudo mkdir -p /srv/mediagoblin.example.org && sudo chown -hR mediagoblin:nginx /srv/mediagoblin.example.org .. 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. + Unless otherwise noted, the remainder of this document assumes that all + operations are performed using this unpriviledged account. -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/ +Install MediaGoblin and Virtualenv +---------------------------------- + +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. -Clone the MediaGoblin repository:: +Change to the MediaGoblin directory that you just created:: - git clone git://gitorious.org/mediagoblin/mediagoblin.git + sudo su mediagoblin -s /bin/bash # to change to the 'mediagoblin' account + $ cd /srv/mediagoblin.example.org -And set up the in-package virtualenv:: +Clone the MediaGoblin repository and set up the git submodules:: - cd mediagoblin - (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:: - 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. + 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:: + + $ git remote set-url origin git://git.savannah.gnu.org/mediagoblin.git + +Set up the hacking environment:: + + $ ./bootstrap.sh && ./configure && make The above provides an in-package install of ``virtualenv``. While this is counter to the conventional ``virtualenv`` configuration, it is @@ -180,26 +252,41 @@ more reliable and considerably easier to configure and illustrate. If you're familiar with Python packaging you may consider deploying with your preferred method. -Assuming you are going to deploy with FastCGI, you should also install -flup:: +.. note:: - ./bin/easy_install flup + What if you don't want an in-package ``virtualenv``? Maybe you + have your own ``virtualenv``, or you are building a MediaGoblin + package for a distribution. There's no need necessarily for the + virtualenv produced by ``./configure && make`` by default other + than attempting to simplify work for developers and people + deploying by hiding all the virtualenv and bower complexity. + + If you want to install all of MediaGoblin's libraries + independently, that's totally fine! You can pass the flag + ``--without-virtualenv`` which will skip this step. + But you will need to install all those libraries manually and make + sure they are on your ``PYTHONPATH`` yourself! (You can still use + ``python setup.py develop`` to install some of those libraries, + but note that no ``./bin/python`` will be set up for you via this + method, since no virtualenv is set up for you!) -(Sometimes this breaks because flup's site is flakey. If it does for -you, try):: +Assuming you are going to deploy with FastCGI, you should also install +flup:: - ./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 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 @@ -209,12 +296,13 @@ Edit site configuration ~~~~~~~~~~~~~~~~~~~~~~~ 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`` and ``paste.ini`` for editing so the original +config files aren't lost (you likely won't need to edit the paste configuration, +but we'll make a local copy of it just in case):: - cp mediagoblin.ini mediagoblin_local.ini + $ cp -av mediagoblin.ini mediagoblin_local.ini && cp -av paste.ini paste_local.ini -Then: +Then edit mediagoblin_local.ini: - Set ``email_sender_address`` to the address you wish to be used as the sender for system-generated emails - Edit ``direct_remote_path``, ``base_dir``, and ``base_url`` if @@ -239,7 +327,7 @@ Update database data structures 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. @@ -250,11 +338,16 @@ Test the Server 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. +The next series of commands will need to be run as a priviledged user. Type +exit to return to the root/sudo account.:: + + exit + .. _webserver-config: @@ -271,12 +364,21 @@ Create a configuration file at ``/srv/mediagoblin.example.org/nginx.conf`` and create a symbolic link 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):: +one of the following commands. + +On a DEB-based system (e.g Debian, gNewSense, Trisquel, Ubuntu, and +derivatives) issue the following commands:: + + sudo ln -s /srv/mediagoblin.example.org/nginx.conf /etc/nginx/sites-enabled/ + sudo systemctl enable nginx + +On a RPM-based system (e.g. Fedora, RedHat, and derivatives) issue the +following commands:: - 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 systemctl enable nginx -Modify these commands and locations depending on your preferences and +You can modify these commands and locations depending on your preferences and the existing configuration of your nginx instance. The contents of this ``nginx.conf`` file should be modeled on the following:: @@ -294,7 +396,7 @@ this ``nginx.conf`` file should be modeled on the following:: gzip on; gzip_min_length 1024; gzip_buffers 4 32k; - gzip_types text/plain text/html application/x-javascript text/javascript text/xml text/css; + gzip_types text/plain application/x-javascript text/javascript text/xml text/css; ##################################### # Mounting MediaGoblin stuff @@ -327,6 +429,11 @@ this ``nginx.conf`` file should be modeled on the following:: alias /srv/mediagoblin.example.org/mediagoblin/user_dev/theme_static/; } + # Plugin static files (usually symlinked in) + location /plugin_static/ { + alias /srv/mediagoblin.example.org/mediagoblin/user_dev/plugin_static/; + } + # Mounting MediaGoblin itself via FastCGI. location / { fastcgi_pass 127.0.0.1:26543; @@ -339,18 +446,36 @@ this ``nginx.conf`` file should be modeled on the following:: } } -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):: +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`` or ``nginx``, + 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. + +Nginx is now configured to serve the MediaGoblin application. Perform a quick +test to ensure that this configuration works:: + + nginx -t + +If you encounter any errors, review your nginx configuration files, and try to +resolve them. If you do not encounter any errors, you can start your nginx +server with one of the following commands (depending on your environment):: 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:: cd /srv/mediagoblin.example.org/mediagoblin/ + su mediagoblin -s /bin/bash ./lazyserver.sh --server-name=fcgi fcgi_host=127.0.0.1 fcgi_port=26543 Visit the site you've set up in your browser by visiting @@ -382,4 +507,9 @@ Security Considerations 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: