Page History
...
Warning | ||
---|---|---|
| ||
This page is still being contiously continuously updated and improved. It is a work in progress. |
Getting ready
Step 1:
...
Install required software
To start working on PR review and testing, the following application applications are needed:
- GitHub login. This lets you add a comment to any PR you test, letting developers know if you found problems or if all your tests were successful.
- GIT https://git-scm.com/downloads
- Install GitHub CLI. This makes it easier to "checkout" (i.e. download) the PR code so you can test it.
- Install Docker Desktop. This is the easiest way to get a DSpace backend installed locally for testing new (frontend or backend) PRs.
- Windows 11: ensure Hyper-V are turned on in the Windows Features (TO ADD). May require administrator rights on the computer.
- Once installed, you will require be required to restart your computer. When first launchlaunched, may have an error mentionning may appear mentioning that WSL for Windows is needed. Is If so, install WSL. When Installing WSL you will be asked for a Linux Distro.
- NOTE: Docker recently changed their service agreement, but Docker remains free for personal use or non-commercial open source projects like DSpace.
NOTE for Windows 10: Docker Desktop can sometimes become a bit "memory-hungry" when it is running. It's best to either disable the "Start Docker Desktop when you log in" setting (so that you it only run it runs when needed). OrAlternatively, if you are using the default WSL2 backend, you can create a ".wslconfig" file in your user directory and limit the amount of memory you let Docker use (at least 4-8GB is recommended if you can spare it):
Code Block title .wslconfig [wsl2] memory=8GB
All set for softwaresCongratulations! You have installed the required software!
Step 2: Set up DSpace Docker
This step must be followed after all software listed in step one are installed, . For detail additional details and most more up-to-date information on DSpace Docker files and configurations, you can refere refer to the documentation on DSpace Github (Docker Compose files for DSpace Backend and Angular Docker Compose files)
...
This operation is done once. It is must be done before beginning to install either DSpace Backend or Frontend.
Actions | Command line | Purpose | Software | ||
---|---|---|---|---|---|
GitHub CLI (gh) authentication |
| Git authentication using github credentials Needed to use Git command. If this is your first time using GitHub CLI (gh), you likely will need to authenticate with it using your GitHub.com login. | Git |
Also possible to use Git Bash:
- Install Git Bash & verify the installation by running "
git version
" from Command Prompt or Powershell - No need to authenticate with Github credentials.
Installing Backend
3-step process (details in table below):
- Cloning the GitHub repository
- Getting the DSPace DSpace Backend images from the Docker Registry
- Starting the Docker Backend Containers
Actions | Command line | Purpose | Software | ||
---|---|---|---|---|---|
Clone the backend codebase |
| Before cloning carefully select your parent folder. Getting all the files needed to run DSpace Backend. This downloads all the code from https://github.com/DSpace/DSpace into a local directory named "DSpace". | Git | ||
Start Docker Desktop | If it is not already running, start Docker Desktop on your machine. It MUST be running for any "docker-compose" or "docker" commands to work.
| Docker | |||
Pull down the latest backend images |
| Pull down the latest backend images from DockerHub. This downloads all the prebuilt Docker images so you don't need to rebuild them locally. | Docker | ||
command line | |||||
Start the Docker DSpace Backend Containers (& automatically install our Entities Test Data) |
| This command | |||
creates the 3 Docker containers for the Backend (dspacedb for the database ; dspacesolr for the solr indexes ; dspace for the backend server ; angular for the frontend UI) and then | |||||
starts them up. Warning: dspacebd is the only Docker container that is not started | |||||
automatically (the | |||||
two others, dspacesolr and dspace, are) The backend will be started with the test data and | |||||
may take a few minutes. It should be completed before moving to the next action. # Wait a few minutes until http://localhost:8080/server/ responds. | Docker | ||||
command line | |||||
Download, install and reindex the test data | |||||
assetstore (of files) |
| ||||
| Docker | ||||
command line | |||||
Check system is up and running | DONE! At this point, you should be able to go to http://localhost:8080/server/ and see a backend similar to https://api7.dspace.org/server/
| Web browser (http://localhost:8080/server/ ) The Hal Browser page is displayed |
Installing Frontend
3 step process (details in table below):
- Cloning the GitHub repository
- Getting the DSpace FrontEnd images from the Docker Registry
- Starting the Docker DSpace Frontend Containers
Actions | Command line | Purpose | Software | ||
---|---|---|---|---|---|
Clone the frontend codebase |
| Getting all files needed to run DSpace frontend (Angular) First, clone the frontend codebase using GitHub CLI (gh). This downloads all the code from https://github.com/DSpace/dspace-angular to a local directory named "dspace-angular". You may wish to run this command from the same parent directory where you cloned the backend (just to keep this new "dspace-angular" folder next to the "DSpace" folder where the backend code resides). | Git | ||
Ensure Docker Desktop is running | If it is not already running, start Docker Desktop on your machine. It MUST be running for any "docker-compose" or "docker" commands to work. On Windows, if Docker Desktop is running, you'll see the Docker whale logo in your taskbar's notification area.Using Docker, pull down the latest frontend images from DockerHub. This downloads all the prebuilt Docker images so you don't need to rebuild them locally. | ||||
Pull down the latest frontend images |
| Using Docker, pull down the latest frontend images from DockerHub. This downloads all the prebuilt Docker images so you don't need to rebuild them locally. | Docker | ||
command line | |||||
Start Docker Container for DSpace frontend/UI |
| This command will create the Docker Container for the Frontend and then start it up. | Docker | ||
command line | |||||
Check UI is up and running |
| Web Browser (http://localhost:4000/) Dspace front page is displayed. |
Step 3: Ensure everything is up and running
...
Your Docker Desktop Containers page should look like followed. The the image below, with the d7 project must contain containing at least 4 containers: dspacedb for the database ; dspacesolr for the solr indexes ; dspace for the backend server ; angular for the frontend UI.
TODO: ALSO ADD PRINT SCREEN OF UI AND BACKEND
...
Once you start the containers either through command lign line or Docker UI, the following URL URLs should be active.
- BachendBackend: http://localhost:8080/server/
- Angular UI: http://localhost:4000/home
- OAI: http://localhost:8080/server/oai/request?verb=Identify
...
- No merge conflict detected (merge conflit conflict tag)
- No changes have been requested by a reviewer (changes requested tags)
- No "work in progress" tag
- All automated test have passed without error
- Looking for an easy one? Look for the "One approval" tag.
...
- Look if a Github Issue is linked to the PR, it usualy usually gives more information on the feature to test.
- If test instructions are unclear, put a comment asking for instructions
- Tester do not need to be assign a PR to test it.
...
If the PR needs a specific configuration, it can be change: recommandation recommendation is to use a local.cfg containing the config value for the test. i.e, if the feature change in the PR use emails, it is necessary to configure SMTP using you SMTP reference.
Testing the DSpace Pull Request (PR)
Testing a Frontend PR | Testing a Backend PR | |
---|---|---|
Move to relevant directory | dspace-angular | DSpace |
Checkout the PR code | Find the number of the Pull Request
| Find the number of the Pull Request
|
Rebuild based on that PR's code | docker-compose -p d7 -f docker/docker-compose.yml build Note: Build duration (Angular): 3-4 minutes with a good bandwith/connexion This will create a new Docker Image including the PR code. | docker-compose -f docker-compose.yml -f docker-compose-cli.yml build Note: Build duration (backend): environ 5-10 minutes with a good bandwith/connexion This will create a new Docker Image including the PR code. |
Start services needed |
Run following command:
|
Run following command:
|
Once you are ready to check the PRs: open Dev tool of you prefered preferred browser
If an error occurs, check the log, either backend or frontend log can be accessed using Docker by clicking on the containers Name (i.e: dspace-angular or dspacedb, etc.)
...