X-Git-Url: https://vcs.fsf.org/?a=blobdiff_plain;f=docs%2Fsource%2Fsiteadmin%2Fdeploying.rst;h=c7b06be0e2426a562f51bca02e232d2d9c63785b;hb=fd4ddeb14ed0f7548158680179df9f5a40902599;hp=34033adcf1c835d7953f033c45aa7701e1cbb1db;hpb=5526150e1a997bc252aa6376e6924f1b6bfff48a;p=mediagoblin.git diff --git a/docs/source/siteadmin/deploying.rst b/docs/source/siteadmin/deploying.rst index 34033adc..c7b06be0 100644 --- a/docs/source/siteadmin/deploying.rst +++ b/docs/source/siteadmin/deploying.rst @@ -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,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 ~~~~~~~~~~~~~~~~~~~~ @@ -77,29 +90,58 @@ 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 su - postgres - sudo -u postgres createuser -A -D mediagoblin +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:: -then create the database all our MediaGoblin data should be stored in:: + # this command and the one that follows are run as the ``postgres`` user: + createuser -A -D mediagoblin - sudo -u postgres createdb -E UNICODE -O mediagoblin mediagoblin +Then we'll create the database where all of our MediaGoblin data will be stored:: + + 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 @@ -125,28 +167,15 @@ 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.:: - 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 -u mediagoblin /bin/bash # (if you have sudo permissions) - -or:: +to log in as this user. To switch to this account, enter:: - su mediagoblin -s /bin/bash # (if you have to use root permissions) + sudo su mediagoblin -s /bin/bash -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``. - -.. 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: @@ -165,62 +194,43 @@ to the unpriviledged system account. 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 @@ -231,23 +241,20 @@ your preferred method. 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 @@ -260,7 +267,7 @@ 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 + $ cp mediagoblin.ini mediagoblin_local.ini Then: - Set ``email_sender_address`` to the address you wish to be used as @@ -287,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. @@ -298,7 +305,7 @@ 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. @@ -321,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 @@ -392,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:: @@ -437,3 +457,7 @@ Security Considerations and restart the server, so that it creates a new secret key. All previous sessions will be invalidated. +.. + Local variables: + fill-column: 70 + End: