From e82857fae672287995c369ff3191dd769d1f503d Mon Sep 17 00:00:00 2001 From: Ben Sturmfels Date: Mon, 11 May 2020 22:32:21 +1000 Subject: [PATCH] docs: Tweak deployment docs headings, link to configuration docs. --- docs/source/siteadmin/configuration.rst | 29 ++++++------ docs/source/siteadmin/deploying.rst | 62 +++++++++++-------------- 2 files changed, 41 insertions(+), 50 deletions(-) diff --git a/docs/source/siteadmin/configuration.rst b/docs/source/siteadmin/configuration.rst index 3df2c9ef..c2cefa1f 100644 --- a/docs/source/siteadmin/configuration.rst +++ b/docs/source/siteadmin/configuration.rst @@ -28,11 +28,16 @@ When configuring MediaGoblin, there are two files you might want to make local modified versions of, and one extra file that might be helpful to look at. Let's examine these. -mediagoblin.ini - This is the config file for MediaGoblin, the application. If you want to - tweak settings for MediaGoblin, you'll usually tweak them here. +``mediagoblin.ini`` + This is the main config file for MediaGoblin. If you want to tweak any + settings for MediaGoblin, you'll usually do that here. -paste.ini +``mediagoblin.example.ini`` + When you run MediaGoblin for the first time, this default config is copied to + your new ``mediagoblin.ini``. Keep this in mind if you need to refer back to + the original settings. + +``paste.ini`` This is primarily a server configuration file, on the Python side (specifically, on the WSGI side, via `paste deploy `_ / `paste script @@ -47,7 +52,7 @@ There's one more file that you certainly won't change unless you're making coding contributions to MediaGoblin, but which can be useful to read and reference: -mediagoblin/config_spec.ini +``mediagoblin/config_spec.ini`` This file is actually a specification for mediagoblin.ini itself, as a config file! It defines types and defaults. Sometimes it's a good place to look for documentation... or to find that hidden @@ -87,8 +92,8 @@ they sound like. - ``email_smtp_use_ssl`` (default is ``False``) - ``email_smtp_force_starttls`` (default is ``False``) -Changing data directory ------------------------ +Changing the data directory +--------------------------- MediaGoblin by default stores your data in wherever ``data_basedir``. This can be changed by changing the value in your ``mediagoblin.ini`` file @@ -120,18 +125,10 @@ All other configuration changes ------------------------------- To be perfectly honest, there are quite a few options and we haven't had -time to document them all. +time to document them all, including Celery configuration. So here's a cop-out section saying that if you get into trouble, hop onto IRC and we'll help you out. Details for the IRC channel is on the `join page`_ of the website. .. _join page: http://mediagoblin.org/join/ - - - - -Celery -====== - -FIXME: List Celery configuration here. diff --git a/docs/source/siteadmin/deploying.rst b/docs/source/siteadmin/deploying.rst index b7e7a737..b870bf45 100644 --- a/docs/source/siteadmin/deploying.rst +++ b/docs/source/siteadmin/deploying.rst @@ -22,9 +22,8 @@ setting up your own instance of MediaGoblin. MediaGoblin most likely isn't yet available from your operating system's package manage, however, a basic install isn't too complex in -and of itself. We recommend a setup that combines -MediaGoblin, virtualenv, Waitress and Nginx on a .deb or .rpm-based -GNU/Linux distribution. +and of itself. We recommend a setup that combines MediaGoblin, +virtualenv and Nginx on a .deb or .rpm-based GNU/Linux distribution. Experts may of course choose other deployment options, including Apache. See our `Deployment wiki page @@ -292,14 +291,15 @@ codebase, you should also run:: update) -Deploy MediaGoblin Services ---------------------------- +Configure Mediagoblin +--------------------- Edit site configuration ~~~~~~~~~~~~~~~~~~~~~~~ Edit ``mediagoblin.ini`` and update ``email_sender_address`` to the address you wish to be used as the sender for system-generated emails. +You'll find more details in ":doc:`configuration`". .. note:: @@ -307,10 +307,7 @@ address you wish to be used as the sender for system-generated emails. may need to edit ``direct_remote_path``, ``base_dir``, and ``base_url``. -.. note:: - The default config is stored in ``mediagoblin.example.ini`` in case - you ever need it. Configure MediaGoblin to use the PostgreSQL database ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -362,11 +359,19 @@ The next series of commands will need to be run as a privileged user. To return to your regular user account after using the system account, type ``exit`` or ``Ctrl-d``. -.. _webserver-config: +Deploy MediaGoblin +------------------ + +The configuration described below is sufficient for development and +smaller deployments. However, for larger production deployments with +larger processing requirements, see the +":doc:`production-deployments`" documentation. + +.. _webserver-config: -Waitress and Nginx -~~~~~~~~~~~~~~~~~~ +Nginx as a reverse-proxy +~~~~~~~~~~~~~~~~~~~~~~~~ This configuration example will use Nginx, however, you may use any webserver of your choice. If you do not already have a web server, @@ -507,19 +512,6 @@ Type ``Ctrl-c`` to exit the above server test and ``exit`` or ``Ctrl-d`` to exit the mediagoblin shell. -.. _create-log-file-dir: - -Create the directory for your log file: ---------------------------------------- - -Production logs for the MediaGoblin application are kept in the -``/var/log/mediagoblin`` directory. Create the directory and give it the -proper permissions:: - - sudo mkdir --parents /var/log/mediagoblin - sudo chown --no-dereference --recursive mediagoblin:mediagoblin /var/log/mediagoblin - - .. _systemd-service-files: Run MediaGoblin as a system service @@ -530,6 +522,13 @@ problems, we need to run it as a system service. If your operating system uses Systemd, you can use Systemd ``service files`` to manage both the Celery and Paste processes. +In the Systemd configuration below, MediaGoblin log files are kept in +the ``/var/log/mediagoblin`` directory. Create the directory and give +it the proper permissions:: + + sudo mkdir --parents /var/log/mediagoblin + sudo chown --no-dereference --recursive mediagoblin:mediagoblin /var/log/mediagoblin + Place the following service files in the ``/etc/systemd/system/`` directory. The first file should be named ``mediagoblin-celeryd.service``. Be sure to modify it to suit your @@ -609,18 +608,13 @@ Assuming the above was successful, you should now have a MediaGoblin server that will continue to operate, even after being restarted. Great job! -.. note:: - - The configuration described above is sufficient for development and - smaller deployments. However, for larger production deployments - with larger processing requirements, see the - ":doc:`production-deployments`" documentation. -.. note:: +What next? +---------- - This configuration supports upload of images only, but MediaGoblin - also supports other types of media, such as audio, video, PDFs and - 3D models. For details, see ":doc:`media-types`". +This configuration supports upload of images only, but MediaGoblin +also supports other types of media, such as audio, video, PDFs and 3D +models. For details, see the ":doc:`media-types`" documentation. .. Local variables: -- 2.25.1