X-Git-Url: https://vcs.fsf.org/?a=blobdiff_plain;f=docs%2Fsource%2Fsiteadmin%2Fdeploying.rst;h=c7b06be0e2426a562f51bca02e232d2d9c63785b;hb=ef2642f7bba3dd61ec2a0b2a2e3a8237e7d9dd1e;hp=de928c8234f15d012a20797f66e0bd9ba2e8226b;hpb=cd1abb1172462488c47730d95e4484ea642bb3ba;p=mediagoblin.git diff --git a/docs/source/siteadmin/deploying.rst b/docs/source/siteadmin/deploying.rst index de928c82..c7b06be0 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,21 +17,38 @@ 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. +.. 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 -------------- @@ -40,25 +57,26 @@ 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 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 ~~~~~~~~~~~~~~~~~~~~ @@ -72,35 +90,58 @@ 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 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 @@ -116,79 +157,126 @@ 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.:: + + 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:: + + 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. + +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. + +To do this, enter either of the following commands, changing the defaults +to suit your particular requirements:: -This document assumes that all operations are performed as this -user. To drop privileges to this user, run the following command:: + sudo mkdir -p /srv/mediagoblin.example.org && sudo chown -hR mediagoblin: /srv/mediagoblin.example.org - su - [mediagoblin] +.. 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 ---------------------------------- -.. note:: +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. - 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. +Change to the MediaGoblin directory that you just created:: -Issue the following commands, to create and change the working -directory. Modify these commands to reflect your own environment:: + sudo su mediagoblin -s /bin/bash # to change to the 'mediagoblin' account + $ cd /srv/mediagoblin.example.org - mkdir -p /srv/mediagoblin.example.org/ - cd /srv/mediagoblin.example.org/ +Clone the MediaGoblin repository and set up the git submodules:: -Clone the MediaGoblin repository:: + $ git clone git://git.savannah.gnu.org/mediagoblin.git -b stable + $ cd mediagoblin + $ git submodule init && git submodule update - git clone git://gitorious.org/mediagoblin/mediagoblin.git +.. note:: -And set up the in-package virtualenv:: + 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:: - cd mediagoblin - (virtualenv --system-site-packages . || virtualenv .) && ./bin/python setup.py develop + $ git remote set-url origin git://git.savannah.gnu.org/mediagoblin.git -.. 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 man 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 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. +your preferred method. Assuming you are going to deploy with FastCGI, you should also install flup:: - ./bin/easy_install flup + $ ./bin/easy_install flup This concludes the initial configuration of the development -environment. In the future, you want update your +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) + Deploy MediaGoblin Services --------------------------- +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:: + + $ cp mediagoblin.ini mediagoblin_local.ini + +Then: + - 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 + your mediagoblin directory is not the root directory of your + vhost. + + Configure MediaGoblin to use the PostgreSQL database ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -206,7 +294,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. @@ -217,18 +305,18 @@ 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. .. _webserver-config: -Connect the Webserver to MediaGoblin with FastCGI -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -This section describes how to configure MediaGoblin to work via -FastCGI. Our configuration example will use nginx, however, you may +FastCGI and nginx +~~~~~~~~~~~~~~~~~ + +This configuration example will use nginx, however, you may use any webserver of your choice as long as it supports the FastCGI protocol. If you do not already have a web server, consider nginx, as the configuration files may be more clear than the @@ -240,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):: - 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 @@ -271,6 +359,10 @@ this ``nginx.conf`` file should be modeled on the following:: # Change this to update the upload size limit for your users client_max_body_size 8m; + # prevent attacks (someone uploading a .txt file that the browser + # interprets as an HTML file, etc.) + add_header X-Content-Type-Options nosniff; + 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; @@ -290,6 +382,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; @@ -302,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 -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:: @@ -325,3 +435,29 @@ Visit the site you've set up in your browser by visiting smaller deployments. However, for larger production deployments with larger processing requirements, see the ":doc:`production-deployments`" documentation. + + +Apache +~~~~~~ + +Instructions and scripts for running MediaGoblin on an Apache server +can be found on the `MediaGoblin wiki `_. + + +Security Considerations +~~~~~~~~~~~~~~~~~~~~~~~ + +.. warning:: + + The directory ``user_dev/crypto/`` contains some very + sensitive files. + Especially the ``itsdangeroussecret.bin`` is very important + 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 invalidated. + +.. + Local variables: + fill-column: 70 + End: