Setup and Run PASS Locally
Last updated
Last updated
The purpose of this article is to guide you through the process of getting PASS up and running locally using . If you're new to Docker, take a look at the . There are many other ways to deploy and run PASS, but this article focuses on getting PASS up and running on a local machine for a preview of the application. If looking to deploy PASS into a production environment, please take a look at the and
Docker
Docker Engine version 20.10.21 or higher
A minimum of 16GB of system memory is required, as Docker uses 8.5GB of virtual memory when starting up all services.
Running PASS locally requires a few simple steps and no configuration, as defaults and demo data are already provided. If you do want to explore the configuration of PASS, the of this page details how to edit the environment file.
The first step is to clone or the code from the PASS Docker repository:
Once you've either cloned PASS docker or extracted it from the ZIP file, then you will want to use a command line tool to navigate to the root directory of PASS docker.
Now that you're at the root directory of PASS Docker run the following command:
After running docker compose you should see the following images being pulled and started running in a container.
nih-user
moo
User that has NIH grants, and submissions on their behalf waiting for approval.
staff1
moo
User that has one NIH Grant, and no submissions.
staff2
moo
User that doesn't have any grants or submissions.
If you need to restart docker and re-run the containers, use the following command:
This will shutdown docker and remove all data associated with the application. This is important because when running docker compose up it loads fake data into the database. If you recreate the containers without previously destroying the data, duplicates will be inserted into the database.
The simple setup contains the workflow of creating a submission and simulating the deposit, but it doesn't actually go anywhere. If you want to test the full integration workflow with deposit services and submitting to DSpace or to NIHMS you can run the following command:
Add an administrator and sample data into DSpace:
The first step is getting the name of the pmc-sftp-server container by running the docker ps command:
It will output the following:
Get the container ID that is associated with atmoz/sftp.Using the container ID enter the SFTP container.
Copy the result from the "Get Container ID" command. Then run the "Enter the SFTP Container" command by replacing the "PasteContainerIDHere" with the previously copied container ID.
Now that you're in the SFTP server, navigate to the deposit. Note: the last directory that is a date will be the date when the deposit is made.
And you will see all the deposits that you've made to NIHMS:
Congratulations! You've simulated a manuscript deposit to the institutional repository (JScholarship) and NIHMS!
All the defaults in the docker env configuration files will run without any modification, but if you need to change a port, URLs, or other configurations you can do so using the .eclipse-pass.local_env file. It's recommend while testing to keep these values the defaults, but if you need to change a port for a specific reason you can do so by modifiying the .eclipse-pass.local_envenvironmental variable file.
Docker Compose Fails to Start the Services
Problem: Users might encounter errors when running the docker compose up command due to various reasons such as network issues, Docker daemon not running, or insufficient permissions.
Insufficient System Memory Error
Problem: The application might fail or perform poorly if the system does not meet the minimum memory requirement.
Solution: Close unnecessary applications to free up memory. Consider increasing your system's memory if persistent issues occur. Ensure you have at least 16GB of system memory available as recommended. If you're running Docker on a Windows machine, ensure that WSL2 and Docker Compose V2 are enabled in the settings.
Unable to Access PASS on the web browser
Problem: After running the Docker compose command, the PASS application does not load or displays an error in the web browser.
Solution: Verify that the containers are running by running the docker ps command. When running without deposit services you should see the following containers running(Note: image version may differ as it will be updated in the future e.g. 1.6.0-SNAPSHOT):
After the container is running, PASS is now running locally on your machine! All you need to do now is navigate to using a web browser, such as Firefox, Google Chrome, or Safari. From there you will see a login screen and can login using these test accounts:
With Deposit Services and DSpace running in the container, when you run through the submission process and submit a manuscript to JScholarship it will make a deposit into DSpace. To view a deposit in the locally running DSpace instance navigate to in your web browser. Login using username:test@test.edu and password: admin.
If submitting a deposit to , you can view the simulated deposit locally in the pmc-sftp-server image that is part of pass-docker.
Solution: Ensure Docker is running on your machine. Check your internet connection and firewall settings. If Docker is running and no networking connections issues are present, then trying updating or installing the .
When running with Deposit-Services and DSpace, as specified in the , you will see the following containers running:
If some of the containers are not running try docker compose -p pass-docker down -v and restart the containers by running the docker compose command mentioned in the or sections.