Docs: add documentation for customizing data locations

docker-compose-custom-data.yml

@@ -31,12 +31,12 @@ services:
     volumes:
       - ${PROXL_UPLOAD_DIRECTORY}:/data/proxl_upload
     environment:
-      proxl_DB_USER: ${MYSQL_USER}
-      proxl_DB_PASSWORD: ${MYSQL_PASSWORD}
-      proxl_DB_HOST_ADDRESS: db
-      proxl_DB_HOST_PORT: 3306
+      PROXL_DB_USER: ${MYSQL_USER}
+      PROXL_DB_PASSWORD: ${MYSQL_PASSWORD}
+      PROXL_DB_HOST_ADDRESS: db
+      PROXL_DB_HOST_PORT: 3306
       PROXL_DB_NAME: ${PROXL_DATABASE_NAME}
-      proxl_JAVA_EXECUTE_PARAMS: ${IMPORTER_JAVA_OPTIONS}
+      PROXL_JAVA_EXECUTE_PARAMS: ${IMPORTER_JAVA_OPTIONS}
       PROXL_WEB_APP_BASE_URL: ${PROXL_WEB_APP_BASE_URL}
   proxl:
     image: mriffle/proxl-webapp:2
@@ -47,8 +47,8 @@ services:
     volumes:
       - ${PROXL_UPLOAD_DIRECTORY}:/data/proxl_upload
     environment:
-      proxl_MYSQL_USER: ${MYSQL_USER}
-      proxl_MYSQL_PASSWORD: ${MYSQL_PASSWORD}
+      PROXL_MYSQL_USER: ${MYSQL_USER}
+      PROXL_MYSQL_PASSWORD: ${MYSQL_PASSWORD}
       PROXL_DATABASE_NAME: ${PROXL_DATABASE_NAME}
     ports:
       - 8080:8080
@@ -60,4 +60,4 @@ services:
       RELAY_HOST: ${SMTP_HOST}
       RELAY_PORT: ${SMTP_PORT}
       RELAY_USERNAME: ${SMTP_USERNAME}
-      RELAY_PASSWORD: ${SMTP_PASSWORD}
+      RELAY_PASSWORD: ${SMTP_PASSWORD}

docker/env-custom-sample

@@ -25,3 +25,9 @@ SMTP_HOST=smtp.example.com
 SMTP_PORT=587
 SMTP_USERNAME=smtp_username
 SMTP_PASSWORD=smtp_password
+
+# Custom data locations, be sure to launch using docker-compose-custom-data.yml
+MYSQL_DATA_DIRECTORY=/data/proxl-data/mysql
+SPECTR_UPLOAD_DIRECTORY=/data/proxl-data/spectr-upload
+SPECTR_STORAGE_DIRECTORY=/data/proxl-data/spectr-storage
+PROXL_UPLOAD_DIRECTORY=/data/proxl-data/proxl-upload

docs/index.rst

@@ -38,6 +38,8 @@ Here you will find documentation for both using and installing proxl locally.
    :caption: Proxl Administration
 
    install/intro
+   install/install-proxl-custom-data-location
+   install/install-proxl-smtp
    install/config
    install/converter_guide
    install/paws

docs/install/install-proxl-custom-data-location.rst

@@ -0,0 +1,119 @@
+===========================
+Customize Data Locations
+===========================
+
+.. note::
+    This tutorial assumes you have completed our :doc:`intro` tutorial through step 4.
+
+By default, our installation tutorial will allow Docker to manage where proxl stores its data. This
+includes things like where MySQL stores its data files, where uploaded scans are stored, and working
+directories for processing uploaded data. On Linux (including Windows running Ubuntu), these data will
+mostly likely be kept under ``/var/lib/docker/``.
+
+It is recommended that you let Docker manage the data directories if you can. However, if you would like to
+customize where the data are stored for proxl, follow the steps below.
+
+1. Create data directories
+================================================
+You will need to create four directories for proxl to store its data.
+
+    1. MySQL data directory. This is the directory used to store the database.
+    2. Spectr upload directory. This the directory used for spectra processing.
+    3. Spectr storage directory. This the directory used to store spectra.
+    4. Proxl upload directory. This is the directory where uploads are temporarily stored.
+
+.. important::
+    If you are using WSL2 on Windows, specifying a Windows filesystem drive (e.g., ``/mnt/d/``) for your
+    data directories is not supported.
+
+For example, if you would like store store all data in the ``/data/proxl-data`` directory, you would type
+the following:
+
+    .. code-block:: bash
+
+        # make a parent directory for proxl data
+        sudo mkdir -p /data/proxl-data
+
+        # make the four directories for storing data
+        sudo mkdir /data/proxl-data/mysql
+        sudo mkdir /data/proxl-data/spectr-upload
+        sudo mkdir /data/proxl-data/spectr-storage
+        sudo mkdir /data/proxl-data/proxl-upload
+
+
+2. Update ``.env`` with data storage locations
+================================================
+The ``.env`` configuration file will need to be updated to include the locations of the data directories.
+Open this file using your favorite text editor. On Linux (including Docker on Windows), we'll assume
+that is ``nano``. To edit the file, type:
+
+    .. code-block:: bash
+
+       # ensure you are in correct directory. if you followed tutorial type:
+       cd ~/proxl
+
+       # edit the file
+       nano .env
+
+Add the following lines to the end of the file. Substitute the actual directories with directories
+you chose above. This example uses the example directory names:
+
+    .. code-block:: none
+
+       MYSQL_DATA_DIRECTORY=/data/proxl-data/mysql
+       SPECTR_UPLOAD_DIRECTORY=/data/proxl-data/spectr-upload
+       SPECTR_STORAGE_DIRECTORY=/data/proxl-data/spectr-storage
+       PROXL_UPLOAD_DIRECTORY=/data/proxl-data/proxl-upload
+
+Type ``Control-o``, ``<ENTER>``, and ``Control-x`` to save and exit ``nano``.
+
+
+3. Starting and Stopping Proxl
+===================================
+
+.. important::
+    The commands below are different than the commands for starting and stopping Proxl on our
+    :doc:`intro` tutorial! You must always use these commands if you have customized the
+    data locations.
+
+At this point, starting and stopping proxl should be straight forward.
+
+To start proxl:
+
+    .. code-block:: bash
+
+       sudo docker-compose -f docker-compose-custom-data.yml up --detach
+
+To stop proxl:
+
+    .. code-block:: bash
+
+       sudo docker-compose -f docker-compose-custom-data.yml down
+
+.. note::
+   If you are using **Windows**, ensure Docker is running by typing:
+
+   .. code-block:: bash
+
+      sudo service docker start
+
+   You should now be able to start Proxl.
+
+.. note::
+   The first time you start proxl, all of the components will download and the database will
+   initialize. This may take a few minutes, depending on your download speed. Subsequent startups
+   of proxl will not require these steps and will be faster.
+
+.. note::
+   These commands must be typed while you are in the project code directory. If you followed these
+   instructions, you can ensure you are in this directory by typing:
+
+   .. code-block:: bash
+
+       cd ~/proxl
+
+
+4. Proceed with installation
+================================================
+You should now proceed to step 6 in our :doc:`intro` tutorial.
+However, recall that your command for stopping and starting is different than that listed in the tutorial. (See above.)

docs/install/intro.rst

@@ -117,6 +117,10 @@ that is ``nano``. To edit the file, type:
 
 Change the passwords and type ``Control-o``, ``<ENTER>``, and ``Control-x`` to save and exit.
 
+.. important::
+    By default, Docker manages where data are stored on your disk. If you would like to customize where proxl
+    stores data, please follow our :doc:`install-proxl-custom-data-location` tutorial. This should be done before
+    continuing on to Step 6 below. Once that is complete, proceed to Step 6.
 
 5. Starting and Stopping Proxl
 ===================================