This documentation will teach how to clone the DXPR builder repository and use it for local development and running DXPR maven tests locally.

Prerequisites

 

Clone and setup DXPR Builder

  1. Open a terminal, if you're on Window make sure it's the Ubuntu terminal you set up in the machine setup guide.
  2. cd into a directory where you store your web projects. For example /mnt/d/dxpr/
  3. Clone the DXPR Builder repository: git clone [email protected]:dxpr/dxpr_builder.git.
  4. Open the project directory in your favorite text editor.
  5. Copy the .env.example file and rename it to be .env
  6. Open the .env file and set the DXPR_ACCESS_TOKEN=[access_token]variable and save the file—ie. ignore the square brackets. You can get your token from the downloads page at dxpr.com in the JSON Web Token tab​​.

  7. Now that you have everything set up, just run the following script inside the dxpr_builder folder by typing this command and wait until the site installs successfully. ./scripts/qa-demo.install.sh.
    This should take several minutes until you see something like this:

    my_drupal9_project_qa_demo |  [notice] Performed install task: install_finished
my_drupal9_project_qa_demo |  [success] Installation complete.
my_drupal9_project_qa_demo | [30-Jul-2021 09:18:32] NOTICE: fpm is running, pid 1
my_drupal9_project_qa_demo | [30-Jul-2021 09:18:32] NOTICE: ready to handle connections

    You only need to run the install command once, next time, just run ./scripts/qa-demo.sh

  8. Open the browser, and navigate to http://drupal.docker.localhost:8000/
  9. Now you can open the project in any editor—eg. VSCode—and start changing files. After saving, the stack will automatically run the grunt tasks, re-build the assets if needed, and keep watching for changes. You can see the logs in the terminal if you need to check for any grunt errors when building assets.
  10. To stop the stack, press CTRL + c. It's always a good way to clean up your environment after stopping the stack, just run this command:  ./scripts/qa-demo.cleanup.sh

 

Do I need to wait for the demo installation every time I run the stack?

Luckily, you won't, the next time you need to run the stack, just run ./scripts/qa-demo.sh that will launch the website In seconds. If you want to stop the stack, do the same as mentioned in step 8 in the Clone and setup section above.

 

Running tests

For running tests, if you followed the steps in the Clone and setup section, just run: ./scripts/qa-demo.test.sh. If not, just follow the Clone and setup section. Also, make sure you stop either the qa-demo.install.sh or the qa-demo.sh commands before running the test command.

 

Troubleshooting

  • Always make sure you set up your .env file before moving on to debugging the errors and make sure nothing is missing there.
  • If your .env file is good, try to stop the currently running command and run the ./scripts/qa-demo.sh command before going further. This will clean up the stack and re-launch the QA demo installation.
  • If it still not working then your QA demo installation might be corrupted, the best course of action is to re-install the stack. Ctrl+c to exit the currently running command, then run this command: ./scripts/qa-demo.install.sh and follow steps 5 through 8 as defined previously in the clone and setup section. If that command throws errors, stop and re-run it again.
  • Always make sure you are not running any of the qa-demo.install.sh, qa-demo.sh, or qa-demo.test.sh commands at the same time even if they are in different terminals cause this will throw errors, you should stop any currently running command then run the desired one.
  • For Mac users, make sure you installed the required libs. Follow this StackOverflow thread.

 

Installing the Bootstrap 4 or 5 demo

  • Create another folder with the dxpr_builder code, for example by copying the existing folder

  • Edit the .env file to switch the environment to Bootstrap 5 (or 4):

    ### DXPR THEME SETUP

### DXPR Theme image tage to use— i.e. production.

DXPR_THEME_TAG=5.x

  • Adjust the project settings to avoid conflicting with the Bootstrap 3 demo by adding bs5 to the below variables and incrementing the port number:

    ### PROJECT SETTINGS

# change to different name in case other instances are running with the same name

PROJECT_NAME=dxpr_builderbs5_project

PROJECT_BASE_URL=drupalbs5.docker.localhost

### The network name where the qa-demo site is using when running the docker stack in the dxp_builder

QA_DEMO_NETWORK=qabs5-demo

# change to different port in case other instances are running on port 8080

PROJECT_PORT=8002
  • To install Bootstrap 4 instead of 5, in the above you replace 5.x with 2.x and replace "bs5" with "bs4"
  • Open the demo at http://drupal.docker.localhost:8002/ where the port number (8002) is the one you entered in the .env file
  • Now run ./scripts/qa-demo.install.sh as usual