PageBuilder and You: A giude to getting started with tronc's (LATMG's?) PageBuilder repository

pagebuilder-and-you.md

PageBuilder and You: A guide to getting started with tronc's (LATMG's?) PageBuilder repository

Welcome!

This guide will walk you, the reader/tronc/latmg developer, through setting up our Arc PageBuilder repository on your local machine for development purposes. Let's get started!

Step 0: Ignore the docs

The default docs in the github repo outline steps for running PageBuilder in vagrant. Ignore them! They are very deprecated and will not work.

Step 1: Install Docker

If you don't have it already, go to the Docker website and install Docker for your OS. Go ahead, I'll wait. . . . Ready to go? Awesome! On to step 2:

NOTE: On Ubuntu 17.10 you will probably need to install docker-compose separately. See this Github issue for more details.

Step 2: Clone the PageBuilder repo

Next you'll need to clone the PageBuilder repository to a directory of your choosing on your computer. I keep all my projects in ~/code/ so for me it went like so:

$ cd ~/code
$ git clone git@github.com:wapopartners/Tronc-PageBuilder-Features.git
$ cd Tronc-PageBuilder-Features

Step 3: Get a dump of the PB database

Next, you'll need to get a dump of the current PB database. I can only assume that in the future we will be able to point our local envs at the real DB, or perhaps have some kind of data-syncing solution. For now, here is how you get a database dump:

1. Log in to the Arc dashboard
2. Click the tile that says PB data
3. Once downloaded, rename the tarball to Tronc-PageBuilder-Features.tar.gz
4. Move it into the /docker/mongo/data directory of your PageBuilder repository

Ex.

$ mkdir ~/code/Tronc-PageBuilder-Features/docker/mongo/data
$ sudo mv ~/Downloads/pb_tronc_prod.tar.gz Tronc-PageBuilder-Features.tar.gz
$ sudo mv Tronc-PageBuilder-Features.tar.gz ~/code/Tronc-PageBuilder-Features/docker/mongo/data

Step 4: Start it up!

Start Docker. This can take awhile. It will ask you for your password so it can run with the correct privileges. Once you type it in, go grab a beer or something and relax for the next 10 minutes or so. . . . Ok. Docker is started. Open a terminal and export the path you cloned into into the PROJECT_REPO environment variable. So for me that would be:

$ export PROJECT_REPO=~/code/Tronc-PageBuilder-Features

Now you are ready to start the app. You can do this by running a NPM command from the /docker/ directory of the repo:

$ cd ~/code/Tronc-PageBuilder-Features/docker
$ npm start

It will take a few minutes for NPM/Docker to spin everything up.

NOTE: I had a problem with the default ports already being allocated on my computer. If you see an error like this:

Creating arc_pagebuilder_proxy ... error

ERROR: for arc_pagebuilder_proxy  Cannot start service proxy: driver failed programming external connectivity on endpoint arc_pagebuilder_proxy (f69268979d968cb28c97d730fb8804f31095993486bf49a349aaf79472d8138c): Error starting userland proxy: Bind for 0.0.0.0:80: unexpected error (Failure EADDRINUSE)

Try editing the ports in the docker-compose.yml file

ports:
-      - 80:80
+      - 8080:80   

With that change above I was able to view the site at the following address: http://localhost:8080. Be aware that this only changes the port that the site runs on. PageBuilder's admin will ALWAYS run on port 8888.

At this point your local site will look pretty bare bones because you haven't built the styles yet. We'll be covering that in Step 6, but first configuration time!

SECOND NOTE: Ubuntu users may have another problem here. If you aren't seeing any content on the site at this point, Docker is probably looking at the wrong content database. Try updating the MONGO_DATABASE var in your Docker env file /Tronc-PageBuilder-Features/docker/.env to Tronc-PageBuilder-Features. This should tell Docker which database to read and allow you to start seeing content.

Step 5: Configuration

Once PageBuilder is running there are a few more steps to get it functioning properly. You should only have to do this once:

1. Go to this page: http://localhost:8888/pb/admin/app/browse/pages.html
2. In the top nav, click on Developer Tools > Runtime Properties
3. In the table, change the value for environment to dev and click save Configuration done!

Step 6: Build the CSS

Ok almost there! Time to build the site itself. Open a second terminal window and navigate to the repo directory. Then execute some npm commands to start the build:

$ cd ~/code/Tronc-PageBuilder-Features
$ npm install
$ npm run dev

This install can also take quite a while; it's a pretty hefty npm project. Go have another beer and relax. Seriously, read a book or watch a short film. You've got time.

NOTE: If you see this during the install process npm ERR! registry error parsing json you're probably ok. Don't Panic.

SECOND NOTE: On the other hand, if during the install process you see errors about npm not being able to find this repo ssh://git@github.com/wapopartners/PageBuilder-gulp.git then you need to be added by the Arc folks. Let me know and I'll get you added to the list.

THIRD NOTE: I ran into an NPM error when trying a straight npm run build. Melissa is looking into it and will get back to me. In the meantime I have found that npm run dev runs without error. And as a bonus it listens for changes as you futz around with the code!

You're done! Happy PageBuildering! Additional details and advanced usage can be found here: https://github.com/wapopartners/Tronc-PageBuilder-Features/tree/dev/docker