Serving Arches with Apache

During development, it’s easiest to use the Django webserver to view your Arches installation. However, once you are ready to put the project into production, you’ll have to use a more efficient webserver like Apache or nginx.

The following is a guide using Apache as an example, split into two sections:

If you want to use nginx + uWSGI instead of Apache + mod_wsgi, this tutorial should get you started.

Configure Apache

The following instructions work for Ubuntu 16.04+, minor changes may be necessary for a different OS. This is a very basic Apache configuration, and more fine tuning will benefit your production installation.

  1. Install Apache.

    $ sudo apt-get install apache2
    
  2. Install mod_wsgi into your Arches virtual environment.

    $ source /home/ubuntu/Projects/ENV/bin/activate
    (ENV)$ pip install mod_wsgi
    
  3. Generate the link path to mod_wsgi.

    (ENV)$ mod_wsgi-express module-config
    

    This command will produce two lines that look like

    LoadModule wsgi_module "/srv/ENV/lib/python3.7/site-packages/mod_wsgi/server/mod_wsgi-py37.cpython-37m-x86_64-linux-gnu.so"
    WSGIPythonHome "/srv/ENV"
    

    Copy these two lines, you will use them in the next step.

  4. Create a new Apache .conf file

    Here is a basic Apache configuration for Arches. If using a domain like heritage-inventory.org, name this file heritage-inventory.org.conf, otherwise, use something simple like arches-default.conf.

    The paths below are based on an example project in /home/ubuntu/Projects/my_project.

    sudo nano /etc/apache2/sites-available/arches-default.conf
    

    Complete new file contents:

    # Paste the text generated by 'mod_wsgi-express module-config' here,
    # *before* the VirtualHost is defined.
    LoadModule wsgi_module "/home/ubuntu/Projects/ENV/lib/python3.7/site-packages/mod_wsgi/server/mod_wsgi-py37.cpython-37m-x86_64-linux-gnu.so"
    WSGIPythonHome "/home/ubuntu/Projects/ENV"
    
    <VirtualHost *:80>
    
        WSGIDaemonProcess arches python-path=/home/ubuntu/Projects/my_project
        WSGIScriptAlias / /home/ubuntu/Projects/my_project/my_project/wsgi.py process-group=arches
    
        # Necessary to support Arches Collector
        WSGIPassAuthorization on
    
        ## Uncomment the ServerName directive and fill it with your domain
        ## or subdomain if/when you have your DNS records configured.
        # ServerName heritage-inventory.org
    
        <Directory /home/ubuntu/Projects/my_project/>
            Require all granted
        </Directory>
    
        # This section tells Apache where to find static files. This example uses
        # STATIC_URL = '/media/' and STATIC_ROOT = os.path.join(APP_ROOT, 'static')
        # NOTE: omit this section if you are using S3 to serve static files.
        Alias /media/ /home/ubuntu/Projects/my_project/my_project/static/
        <Directory /home/ubuntu/Projects/my_project/my_project/static/>
            Require all granted
        </Directory>
    
        # This section tells Apache where to find uploaded files. This example uses
        # MEDIA_URL = '/files/' and MEDIA_ROOT = os.path.join(APP_ROOT)
        # NOTE: omit this section if you are using S3 for uploaded media
        Alias /files/uploadedfiles/ /home/ubuntu/Projects/my_project/my_project/uploadedfiles/
        <Directory /home/ubuntu/Projects/my_project/my_project/uploadedfiles/>
            Require all granted
        </Directory>
    
        ServerAdmin webmaster@localhost
        DocumentRoot /var/www/html
    
        # Available loglevels: trace8, ..., trace1, debug, info, notice, warn,
        # error, crit, alert, emerg.
        # It is also possible to configure the loglevel for particular
        # modules, e.g.
        #LogLevel info ssl:warn
        # Recommend changing these file names if you have multiple arches
        # installations on the same server.
        ErrorLog /var/log/apache2/error-arches.log
        CustomLog /var/log/apache2/access-arches.log combined
    
    </VirtualHost>
    
  5. Disable the default Apache conf, and enable the new one.

    $ sudo a2dissite 000-default
    $ sudo a2ensite arches-default
    $ sudo service apache2 reload
    

    Replace arches-default with the name of your new .conf file if needed.

At this point, you can try accessing your Arches installation in a browser, but you’re likely to get some kind of file permissions error. Continue to the next section.

Important

With Apache serving Arches, any changes to a .py file (like settings.py) will not be reflected until you reload Apache.

Prepare the Arches Project

  1. Set all file and directory permissions.

    Apache runs as the user www-data, and this user must have write access to some portions of your Arches project.

    Note

    On CentOS, Apache runs as is httpd, so substitute that for www-data herein.

    The arches.log file…

    $ sudo chmod 664 /home/ubuntu/Projects/my_project/my_project/arches.log
    $ sudo chgrp www-data /home/ubuntu/Projects/my_project/my_project/arches.log
    

    The uploadedfiles directory…

    $ sudo chmod 775 /home/ubuntu/Projects/my_project/my_project/uploadedfiles
    $ sudo chgrp www-data /home/ubuntu/Projects/my_project/my_project/uploadedfiles
    

    Or, if either arches.log or uploadedfiles doesn’t yet exist, you can just allow www-data to create them at a later point by giving write access to your project directory.

    $ sudo chmod 775 /home/ubuntu/Projects/my_project/my_project
    $ sudo chgrp www-data /home/ubuntu/Projects/my_project/my_project
    

    You should now be able to access your Arches installation in a browser, but there is one more important step.

  2. Run collectstatic.

    This Django command places all of the static files (CSS, JavaScript, etc.) used in Arches into a single location that a webserver can find. By default, they are placed in my_project/my_project/static, based on STATIC_ROOT.

    Note

    You can change STATIC_ROOT all you want, but be sure to update the Alias and Directory info in the Apache conf accordingly.

    (ENV)$ python manage.py collectstatic
    

    The first time this runs it will take a little while (~20k files), and may show errors/warnings that you can safely ignore.

    Important

    from now on, any time you change a CSS, JavaScript, or other static asset you must rerun this command.

You should now be able to view your Arches installation in a browser without any issues.