From 4d8e2e88b03377ba4abc3135d91e8ce26bd6b1fd Mon Sep 17 00:00:00 2001 From: kthoden Date: Tue, 9 Jun 2020 09:37:00 +0200 Subject: [PATCH 1/3] Credits --- docs/conf.py | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/conf.py b/docs/conf.py index 5db3dc3..254a035 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -20,8 +20,8 @@ # -- Project information ----------------------------------------------------- project = 'EOA Publication Platform' -copyright = '2020, Klaus Thoden' -author = 'Klaus Thoden' +copyright = '2020, Max Planck Institute for the History of Science' +author = 'Samuel Gfrörer and Klaus Thoden' # The full version, including alpha/beta/rc tags release = '1.5' From 0067b24338d2b35d69cb5110023c1b65c11bf55b Mon Sep 17 00:00:00 2001 From: kthoden Date: Tue, 9 Jun 2020 12:53:07 +0200 Subject: [PATCH 2/3] Docker documentation --- docs/install_docker.rst | 144 ++++++++++++++++++++++++++++++++++++++++ 1 file changed, 144 insertions(+) diff --git a/docs/install_docker.rst b/docs/install_docker.rst index 2209cf1..277f8b7 100644 --- a/docs/install_docker.rst +++ b/docs/install_docker.rst @@ -1,3 +1,147 @@ ========================== Installation with Docker ========================== + +Docker is used to provide a consistent environment. Additional Python scripts are used for automisation of the installation process. + +Dependencies to other git repositories are handled using `git_deps_py `_. + +Configuration +============= +- Environment variables: see file ``.env`` + + These variables are available inside the ``docker-compose.yaml`` file and are also loaded into the Python scripts. + (The ``.env`` file is initially created with default settings by the ``init.py`` script) + +- Django settings: see ``src/eoa/settings.py`` + + For further information please check the Django documentation. + +Prerequisites +============= + +- Python 3 +- Docker, Docker Compose +- `git_deps_py `_ + +Initialise the Repository +========================= +Initialise the repository with the following commands:: + + $ git_deps_py + $ ./scripts/init.py --build + +This will pull remote repositories and resources, initialize the database, etc. +The ``--build`` parameter forces the recreation of the docker image, e.g. if ``Dockerfile`` or ``requirements.txt`` have changed. + +Import data +=========== + +Initialize CMS pages +-------------------- +The dummy fixture contains the default setup for CMS pages. +Also a CMS superuser with username ``test`` and password ``test`` (don't use this in production !):: + + $ cp fixtures/cms_dummy.json res/fixtures/ + $ ./scripts/init.py --skip-db + $ ./scripts/run.py && ./scripts/exec_in_container.py + $ $ python manage.py loaddata $RES_DIR/fixtures/cms_dummy.json + $ $ exit + $ ./scripts/stop.py + +Import Publications +------------------- + +In order to publish a publication on the platform, the following steps are necessary: + +#. Using the conversion workflow (`EOASkripts `_), produce a Django-XML version of a publication. + +#. Import it into the EOA Publication Platform + +For the example publication, this process goes as follows: + +1. Compile the example + +Compile the example file found in `eoa-publication-model `_. For other examples containing TEI-XML consult https://github.molgen.mpg.de/EditionOpenAccess/EOASkripts#the-tei-workflow-tei---pdf-django-epub:: + + $ cd example_import + $ git_deps_py --store-dir ../dependencies + $ cd dependencies/EOASkripts + $ ./scripts/run.py && ./scripts/exec_in_container.py + $ $ process_eoa_latex.py input/example/124_eoatex + $ $ exit + $ ./scripts/stop.py + $ cd ../../../ + +2. Import example into the platform + +After the creation of Django-XML, import it into the platform:: + + $ mkdir res/publications + $ cp -r example_import/EOASkripts/runtime/output/124_eoatex/django res/publications/example + $ ./scripts/init.py --skip-db + $ ./scripts/run.py && ./scripts/exec_in_container.py + $ $ python manage.py publicationimport $RES_DIR/publications/example + $ $ exit + +Visit http://localhost:8001/ for the main site and http://localhost:8001/studies/124/index.html for the example publication. Go to http://localhost:8001/admin/login/ to access the Django administration pages, using above credentials. + +Stop the container with:: + + $ ./scripts/stop.py + +Configure Project specific Information +-------------------------------------- + +In order to tweak the CMS pages, log in to the CMS and edit them. + +To change the organisation information (name, logo, ...), edit the files in ``res/custom_config/*`` and then perform :: + + $ ./scripts/init.py --skip-db + +To add a logo and a favicon, copy the files into ``res/static/custom_static/``. Files in this directory overwrite default files with the same name:: + + $ cp res/static/custom_static/ + $ ./scripts/init.py --skip-db + + +.. note:: + The templates expect some pages to exist in the CMS: + + - Introduction Page (id: ``introduction``) + - Contact (id: ``contact``) + - Imprint (id: ``imprint``) + + Deleting those might break things. + + +Useful commands +=============== +Run the Webserver:: + + $ ./scripts/run.py + +The webpage can now be explored in your local browser. + +Stop the Webserver:: + + $ ./scripts/stop.py + +Run Command in the Webserver container:: + + $ ./scripts/exec_in_container.py '[ CMD ...]' + +Clean the Repository:: + + $ ./scripts/exit.py + +This should remove all remote repositories and resources not part of this repository. +Docker images are not deleted though. + +Export Data +=========== + +In order to export CMS content, run:: + + $ ./scripts/run.py && ./scripts/exec_in_container.py 'python manage.py dump_cms' + $ cp runtime_data/fixtures/* fixtures/ From c1f2c59a84714e8cc5dc3b71de8c6c428e556359 Mon Sep 17 00:00:00 2001 From: kthoden Date: Tue, 9 Jun 2020 16:03:27 +0200 Subject: [PATCH 3/3] Virtual environment documented --- docs/conf.py | 6 ++- docs/install_docker.rst | 2 +- docs/install_venv.rst | 92 +++++++++++++++++++++++++++++++++++++++++ 3 files changed, 98 insertions(+), 2 deletions(-) diff --git a/docs/conf.py b/docs/conf.py index 254a035..c4badd5 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -70,5 +70,9 @@ # -- Options for intersphinx extension --------------------------------------- +DOC_URL = "http://localhost:7999" + # Example configuration for intersphinx: refer to the Python standard library. -intersphinx_mapping = {'https://docs.python.org/3/': None} +intersphinx_mapping = {'main': (f'{DOC_URL}/', None) + 'webplat': (f'{DOC_URL}/webdesign_platform', None), +} diff --git a/docs/install_docker.rst b/docs/install_docker.rst index 277f8b7..a2b1e67 100644 --- a/docs/install_docker.rst +++ b/docs/install_docker.rst @@ -2,7 +2,7 @@ Installation with Docker ========================== -Docker is used to provide a consistent environment. Additional Python scripts are used for automisation of the installation process. +Docker is used to provide a consistent environment. Additional Python scripts are used for automisation of the installation process. This solution also contains the EOASkripts suite, which effectively makes this an all-in-one-solution for the whole production infrastructure. Dependencies to other git repositories are handled using `git_deps_py `_. diff --git a/docs/install_venv.rst b/docs/install_venv.rst index d175874..2e5601d 100644 --- a/docs/install_venv.rst +++ b/docs/install_venv.rst @@ -1,3 +1,95 @@ ======================================= Installation with Virtual Environment ======================================= + +As a slightly more lightweight approach, the whole system can also be set up in a Virtual Environment. This solution will definitely be lighter on system resources like disk space and memory. + + +Python packages +=============== +If not done already, install the following packages (on Linux):: + + sudo apt-get install python3-venv virtualenv + +EOA Publication Platform +======================== +Clone the source files for the publication platform:: + + git clone https://github.molgen.mpg.de/EditionOpenAccess/eoa-1.5.git + + +Additional deployment steps +=========================== +.. note:: + A small note before you continue, as it is not easy to move a virtual environment after installation. + +If you plan to use this installation on a production server, consider the additional steps of creating a separate user and a daemon and running the service in a non-user directory for more security and stability. See :doc:`the main documentation `. + + +Create Virtual Environment +========================== +You are free to choose a name of your choice here:: + + virtualenv -p python3 eoapp_ve + cd eoapp_ve + source bin/activate + +Installation of the system +-------------------------- +The next steps set up the EOA Publication Platform:: + + pip install djangocms-installer lxml + djangocms --django-version 2.1 --cms-version stable eoapp + pip uninstall djangocms-googlemap + +Submodules – Further development planned? +----------------------------------------- +If you plan on further developing the submodules of the platform, consider using the following commands for installation. With this, the submodules are located in the ``src`` directory on root level and in version control:: + + pip install -e git+https://github.molgen.mpg.de/EditionOpenAccess/django-eoapublications.git#egg=django-eoapublications + pip install -e git+https://github.molgen.mpg.de/EditionOpenAccess/django-eoaauthors.git#egg=django-authors + pip install -e git+https://github.molgen.mpg.de/EditionOpenAccess/django-eoaseries.git#egg=django-series + pip install -e git+https://github.molgen.mpg.de/EditionOpenAccess/django-eoaforthcoming.git#egg=django-forthcoming + pip install -e git+https://github.molgen.mpg.de/EditionOpenAccess/django-opds.git#egg=django-opds + +Otherwise, use these commands to install them deeper in the system:: + + pip install git+https://github.molgen.mpg.de/EditionOpenAccess/django-eoapublications + pip install git+https://github.molgen.mpg.de/EditionOpenAccess/django-eoaauthors + pip install git+https://github.molgen.mpg.de/EditionOpenAccess/django-eoaseries + pip install git+https://github.molgen.mpg.de/EditionOpenAccess/django-eoaforthcoming + pip install git+https://github.molgen.mpg.de/EditionOpenAccess/django-opds + +Adding the webdesign and templates and settings +----------------------------------------------- +If you haven't done so yet, see the :doc:`webdesign documentation ` for installation and usage. For the webdesign, you need the ``app.js`` and ``app.css`` files as well as the ``assets`` directory. After having built these files or obtained them from another source, copy them into the new platform:: + + cd /dist + cp -r app.* assets/ /eoapp/eoapp/static/ + +Similarly, add the templates and settings from the EOA-1.5 repository:: + + cd + rm -r eoapp/eoapp/templates + cp -rv /src/eoa/templates /eoapp/eoapp/ + cp /src/eoa/settings_lite.py /eoapp/eoapp/settings.py + cp /src/eoa/urls.py /eoapp/eoapp/ + +Importing data and setting up the database +========================================== +Import some basic CMS pages and settings:: + + cd eoapp + python manage.py loaddata /fixtures/cms_dummy.json + +Finally, update the database by migrating:: + + python manage.py makemigrations + python manage.py migrate --run-syncdb + + +Run the server +============== +It should now be possible to run a server and access the site through the browser:: + + python manage.py runserver 0.0.0.0:8000