A Girder plugin for a Technical Journal
Project description
Assumes a certain folder structure so far for the main page display: The top level collection ID value is what should be used in the configuration page It will then search for the folders under each, to find all available journal “issues”
From each of those “issues”, it will query for a “submission” which is an available folder in the “issue”. Eventually, this folder will have metadata for the rest of the information that needs to be shown. A sample structure is found in a graphic diagram below, with the Girder type in parenthesis:
OTJ (collection) ├── 2016 Jan-Jun (folder) │ ├── Submission 1 (folder) │ │ └── Revision 1 | | └── blah.tar │ │ └── Revision 2 | | └── blah_v2.tar │ └── Submission 2 (folder) │ │ └── Revision 1 │ └── Paper.docx └── 2016 Jun-Dec (folder) └── Submission 3 (folder) └── Revision 1 └── Paper2.docx
Setup Instructions
Install pre-requisite programs
Follow the Girder System Prerequisites documentation to ensure that all necessary programs are available for the pip-installed version of Girder.
Note: The Technical Journal plugin requires Node.js 8+. When following the documentation to enable the Node.js APT repository, use:
curl -sL https://deb.nodesource.com/setup_8.x | sudo -E bash -
Note: The Technical Journal plugin requires that MongoDB is at least 3.4+. When following the documentation to install MongoDB, replace ‘3.2’ with ‘3.4’
echo "deb http://repo.mongodb.org/apt/debian jessie/mongodb-org/3.4 main" \
| sudo tee /etc/apt/sources.list.d/mongodb-org-3.4.list
or
echo "deb http://repo.mongodb.org/apt/ubuntu xenial/mongodb-org/3.4 multiverse" \
| sudo tee /etc/apt/sources.list.d/mongodb-org-3.4.list
Set up Technical Journal plugin
The plugin can either be installed directly from pip:
pip install girder-tech-journal
Or by cloning this repository
git clone https://github.com/girder/tech_journal
cd tech_journal
pip install .
In the git repo directory, follow the Installation documentation to create a virtual environment and install Girder from pypi. Do not install the web client libraries yet. The following instructions assume you have entered the virtual environment.
Install yarn
npm install -g yarn
Install web packages:
cd girder-tech-journal-gui
yarn install
To run the development server:
yarn run serve
To build the standalone web application for production:
yarn run build
If you’ve cloned the repo and are developing for the plugin, there is a custom command in setup.py that will automate installing yarn packages, building the frontend for production, and copying the dist folder to the proper location. To use this, run: python setup.py build_ui.
WARNING
If you run girder serve in development mode, the standalone frontend will not be served at /tech_journal. This is because it is expected that the frontend will be served on its own (E.g. yarn run serve) in order to see the changes being made. If for some reason you need to serve the frontend at /tech_journal, you will need to run girder serve in production mode. However be aware that in this case it is serving the pre-built files, and thus no changes will take affect until you rebuild the frontend (E.g. by running python setup.py build_ui).
Install girder_worker
The submission upload page has the capability to submit a GitHub URL and have the Tech Journal download the master branch of the repository to be made available as the download of the submission. To do this, it utilizes the girder_worker tool. This is automatically installed when installing the Tech Journal plugin.
Install RabbitMQ
Follow RabbitMQ documentation to install.
After installation, ensure that the service is running
service --status-all | grep rabbitmq [ + ] rabbitmq-server
Install Tech Journal Tasks
The package found in the tech_journal_tasks directory will also need to be installed into the environment prior to starting the girder_worker program.
This is accomplished by entering the tech_journal_tasks directory and executing the setup.py file with the install directive.
cd tech_journal_tasks
pip install .
Start girder_worker
Executing the girder_worker program will start the task listener. If one has accepted the default installation for RabbitMQ, there will be no changes necessary to the girder_worker configuration to allow it to connect to RabbitMQ. Start girder_worker with the following command:
girder-worker -l info
When viewing the first set of output, ensure that the processGitHub and surveySubmission tasks are listed under the [tasks] header:
snyder@midas-vm:~$ girder-worker -l info <....> [tasks] . girder_worker.docker.tasks.docker_run . girder_worker.run . tech_journal_tasks.tasks.processGithub . tech_journal_tasks.tasks.surveySubmission
Configure the plugin
Open a new terminal and activate the virtual environment.
cd tech_journal
. ~/girder_env/bin/activate
Build the Girder web client and start the server:
girder build
girder serve
Note: although ordinarily Girder would want to rebuild the newly activated plugin, you do not need to do that now, since we are building this plugin in a “standalone” mode, outside the control of Girder’s build system
Create Admin User
Open http://localhost:8080/ in your web browser, and you should see the Girder welcome page.
The first user to be created in the system is automatically given admin permission over the instance, so the first thing you should do after starting your instance for the first time is to register a user. After that succeeds, you should see a link appear in the navigation bar that says Admin console.
Generate Folder Structure
First, generate a “Collection” to represent the total information of the OTJ. This can be accomplished by clicking on Collections in the left menu and then clicking on the Create Collection button. Enter a name and a description, then click Create.
This creation of the collection can also be done by utilizing the plugins/admin/journal page of the OTJ.
Note The description of the collection must contain the string __journal__ to be picked up by certain OTJ pages.
The “Unique ID” of this folder, which can be found by clicking on the blue button with an i on it, will be used later to configure the Tech Journal plugin.
Then, generate a folder within that collection to be the first “Issue” that will be submitted to. This is accomplished by clicking on the Collection Actions menu and selecting Create folder here. The Collection Actions button can be found to the right of the blue button from above. Enter a name and description for the first folder and then click “Create” again.
Enable the Technical Journal plugin
To enable the plugin, head to the Admin Console and click on the Plugins link.
A list of the current plugins will be shown, scroll down to the Technical Journal Plugin and enable it by switching the OFF slider to the on position.
Click on the Configure Plugin icon, which looks like a small gear.
This will show the 5 fields that are used to configure a Midas instance of the Technical Journal. Only the Default Journal entry will need to be filled out at this point. Enter the Unique ID of the collection that was generated above and click Save Configuration.
Once that has been saved, the plugin should be configured and ready to be used. Visit the entry point of the plugin by visiting:
http://<webroot>/tech_journal
Or something like this for a localhost instance:
http://localhost:8080/tech_journal
WARNING
Some of the links, Journal and Help, in the menu bar do not point to valid locations within the plugin yet. The Home and New Submission links will take you to the correct pages.
Releasing
To update the PyPI release:
First increment the version is setup.py. Then run:
cd girder-tech-journal-gui;
yarn run build;
cd ..;
python setup.py sdist;
tox -e release
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.