WPP - a Wordpress based webapp with decoupled VueJS and SPA front-end

WPP is a software that encompass WordPress as a admin and API solution, connected to a decoupled VueJS/SPA webapp. It includes a custom WordPress plugin that, depending on the user agent, allows rendering the webpages as pure html (for SEO) and several other integrations for authentication, user dashboard on the SPA app, map, menu and slide components.

Sections

• Running locally
• Features
• Highlighted features
  • Auto update WordPress URL
  • Decoupled front-end
  • Contact form
  • Visitor dashboard
  • Map component
  • Members
  • Image slider and gallery
  • Site sections
• WPP plugins
• Customization and updates
• Setup environment
• Debug
• Deploy
• Options

Example web app

An web app using this solution can be seen live on fam.eco

Running locally

1. First, make sure you have the requirements installed according Setup environment.

2. Clone the project from the gitlab repository

3. Go to the project root folder and run:

   # wordpress create files programmatically and therefore it needs the permissions to do that.
   sudo chmod 777 -R wordpress/wp-content
   
   # run the docker compose solution
   docker-compose -f local.docker-compose.yml up -d
   
   # then, when the docker-compose build and all the services are ready, run:
   docker exec wpp-website-local /bin/sh -c 'cd wp-content && sh update.sh'
   # important: it is necessary to be in the right folder, like `wp-content`,
   # so the wp-cli can use the right context

Features

• Custom docker image based in wordpress:5.3-php7.1-apache
• Custom docker image based in mysql:5.7 with auto dump import
• wp-config.php mapped to an external file
• wp-content folder mapped to an external folder
• Customization and updates via update.sh and wp-cli
• Decoupled front-end with VueJS and SPA
• Auto fix wordpress url to match the one defined in the docker-compose yml file
• Auto update state via wp-cli

Highlighted features

Some important features are described in this section

• Auto update WordPress

  WordPress store in db absolute urls and therefore we check if the url defined in the docker-compose yml file matches the one stored by WordPress. If not, we update it automatically. Like this we can run the same project and db in multiples environments, like local, staging and production. See https://codex.wordpress.org/Changing_The_Site_URL

• Decoupled front-end

  This solution includes a decoupled front-end dashboard built using VueJS and a custom base front-end application. The front-end communicates with the wordpress rest json api (including the custom endpoints created by the custom plugins) to get and send data.

• Contact form

  This solution includes a decoupled front-end contact form with captcha and the back-end services to process it

• Visitor dashboard

  A decoupled front-end visitor dashboard and the back-end services to process it

• Map component

  A map component that allows the creation of map views on the admin to display a place, list of places and static routes. The icon of the place can be customized and each place displayed on the map can be linked to a content and is navigable (clickable)

• Image slider and gallery

  This solution includes a slider component and a gallery component

• Members

  This solution includes member component that allows creating members and listing them on any page or post. It is also possible to link a member to a user/author

• Site sections

  This solution includes a component that allows creating/editing sections. Each section can have its appearance customized and content can be created under it.

See more about the front-end on the Front-end app readme

Wpp WordPress plug-in

This plug-in is custom wpp solution and is intended to contain customizations to WordPress hooks/events, custom rest-api endpoints as well as customize third parties plugins that are supposed to be installed.

• It registers custom wp api end-points related to user registration and custom wpp data regarding the business logic, like sectors and usernames available (in wp-api folder). The dashboard app uses these endpoints to communicate with the back-end during user registration and profile update.
• It also register custom actions for WordPress rest_api_init to customize the response and return custom user data as well as custom error messages when the user api is called. In addition it also adds a filter to the jwt_auth_token_before_dispatch event thrown by the jwt-authentication-for-wp-rest-api plugin (in includes/users.php).

Customization and updates

We keep a file in the wp-content mapped volume/folder named update.sh. This file is responsible for update the current installation, including anything related to WordPress world, like plug-ins, themes and the stuff related to the decoupled front-end. The update.sh file is an ordinary shell script file and any Linux command can be executed there, considering you run it inside the docker-container.

To manage and update the WordPress stuff we use the pre-installed WP CLI tool that allows to run several tasks in a programmatic way in a WordPress installation, like add, activate and delete plug-ins, add users, change user's password, update options, change menu and so on. check the full list at WP CLI commands

Example to add and activate a plug-in:

1. Open the file wordpress/wp-content/update.sh in the local installation and add the desired command, like:

   wp plugin install <plugin-name> --activate --allow-root
   # --allow-root is always necessary because inside the container the command is been ran as root

   Important: the existing lines must be kept to keep the correct state. If a plugin is already installed, it will not be changed.

2. Run the updater locally:

   # important: it is necessary to be in the right folder, like wp-content, so the wp-cli can use the right context
   docker exec wpp-website-local /bin/sh -c 'cd wp-content && sh update.sh'

Setup environment

To install docker, docker-compose and docker-machine you can use the setup-docker.sh script in the scripts folder.

# give it execution permission
sudo chmod +x ./scripts/setup-docker.sh

# run the script
./scripts/setup-docker.sh

If you encounter any problems with the installation script, you can still open the setup-docker.sh and run every command line for line.

If you run into a docker-compose Version ... is not supported error upon running the project, try to install a newer docker-composer version:

# remove current `docker-compose`
which docker-compose
# e.g /usr/local/bin/docker-compose
sudo rm /usr/local/bin/docker-compose

# install newer docker-compose version
sudo curl -L https://github.com/docker/compose/releases/download/1.20.0/docker-compose-`uname -s`-`uname -m` -o /usr/bin/docker-compose

# give it execution permission
sudo chmod +x /usr/bin/docker-compose

Should docker not be able to get the wp-cli.phar from the remote source you have enable this for docker:

# create daemon.json file
sudo touch /etc/docker/daemon.json

# edit the file with a editor e.g. vim
sudo vim /etc/docker/daemon.json

In here you need to insert your DNS addresses in the following format:

{
   "dns": ["your-primary-dns-ip", "your-secondary-dns-ip"]
}

You can look up your DNS addresses for example with the nmcli command. (DNS configuration: servers: IPv4 IPv6)

Afterwards restart the docker container: service docker restart

If you need to run the web-application in production or development mode:

# access the docker container
docker exec -it wpp-website-local bash

# go to folder
cd ../webapp

# install npm and run build (or dev for development mode)
npm install
npm run build

Auto update state via WP CLI

WP CLI allows to run several tasks in a programmatic way in a wordpress installation, like add, activate and delete plugins, add users, change user's password, update options, change menu and so on. check the full list at WP CLI commands

Example to add and activate a plug-in:

1. Open the file wordpress/wp-content/update.sh in the local installation and add a line, like:

   wp plugin install <plugin-name> --activate --allow-root
   # --allow-root is always necessary because inside the container the command is been ran as root

   Important: the existing lines must be kept to keep the correct state. If a plugin is already installed, it will not be changed.

2. Run the updater locally:

   docker exec wpp-website-local /bin/sh -c 'cd wp-content && sh update.sh'

3. Commit in the develop branch (this branch has no deploy CI integration)

4. Deploy to staging server by committing in the staging branch (the Gitlab CI will install it on the staging server)

5. Check if everything is as desired accessing the staging url

6. Deploy to production server by committing in the master branch (the Gitlab CI will install it on the production server)

Important: If CI integration is set up the updater is automatically ran by the CI integration during the deploy to staging and production server

Important: the auto update does not run locally. See Running locally

Running locally the back end

To run the project locally, go to the project root folder and run:

docker-compose -f local.docker-compose.yml up -d

Important: when all the services are ready, run

docker exec wpp-website-local /bin/sh -c 'cd wp-content && sh update.sh'

If you want to run the webapp in dev mode, do the following:

• From the example files, create a copy of config.js and theme.js files in /webapp/src/config folder, without the -example in their names.
• Make sure the local.docker-compose.yml is running
• run, in webapp folder:

npm run dev

Debug

Check the how to debug readme to set up the php debug for the php code.

Deploy

The project deployment can be done via git push/pull or via continuous integration with Gitlab CI (rename the gitlab-ci-deactiveated.yml to gitlabp-ci.yml and adjust the credentials). In the second case, when you push a commit to the staging branch the changes in this branch will be deployed to the STAGING server and when you push a commit to the master branch the changes in this branch will be deployed to the MASTER server.

Remember that if you make changed on the dashboard app, if is necessary to build it locally before commit/deploy. Check the build-and-deploy app section to understand more.

Options

All WPP Options starts with wpp_ prefix, except:

• git_hub_client_secret
• recaptcha_secret
• wpp_recaptcha_site_key

Options with wpp_ prefix that are not present by default:

• wpp_signup_with_github
• wpp_site_relative_login_logo_url
• wpp_ors_api_key
• wpp_map_icon_url
• wpp_meta_*
• wpp_meta_name_*
• archive_sections_sidebar
• wpp_meta_theme-color
• wpp_search_title_translation
• hide_developedby
• wpp_slider_transition - for transition options see: https://deulos.github.io/vue-flux/
• wpp_site_title_translations
• wpp_site_description_translations
• wpp_search_title_translation
• wpp_use_and_data_policy_url_ (like wpp_use_and_data_policy_url_en-us)

Custom post type supports used on back-end

• parent_section (if the post type must have a parent section)
• section_in_permalink (if the parent section must appear in the permalink)
• notification (if the content must generate a notification)
• feed (if the content must be listed in feed)
• auto_related (if the post type must be listed as related to other posts automatically, based on section and categories)

ACF extras

Possible post extras:

• no_link (boolean)
• resizable (boolean)
• target_blank (boolean)
• not_searchable (boolean)
• medias
• custom_link (string/url)
• imported_id (integer)
• available (boolean)
• available_at (date, format Ymd)
• has_places (boolean)
• sponsored (boolean)
• places (array of posts)
• has_route (boolean)
• polyline (textarea/string representing a pplyline array)
• hide_author_bio (boolean) hide author bio in single mode
• show_sidebar (boolean)
• sidebar_post_types (array of strings)
• max_in_side_bar (integer)
• custom_post_date (date, format Ymd)
• prepend (integer, adding prepend post id)
• append (integer, adding append post id)
• hide_newsletter_sidebar (boolean)
• tile_provider_id (osm, satellite, topography, transport-dark or cycling)
• zoom (a value from 1 to 18)
• places [object] containing child objects with place id and inside each, the props:
  • link
  • title
  • id
  • center_lat
  • center_lng
  • link
  • locale
  • title
  • zoom
• routes [array] each containing: (auto added from map_route post type)
  • means_of_transportation
  • polyline
  • title
  • id
• map_icon_url
• Maps:
  • show_places_by_default

Only for pages:

• has_top_highlighted
• has_middle_highlighted
• has_bottom_highlighted
• highlighted_top_title
• highlighted_middle
• highlighted_bottom
• highlighted_top
• highlighted_middle_title
• highlighted_bottom_title

Possible section extras:

• has_image_slides (boolean)
• html_content (text/html)
• list_posts (boolean)
• list_post_endpoints (array of strings)
• compact_list_posts (boolean)
• compact_list_post_endpoints (array of strings)
• set_custom_appearance (boolean)
• bg_image (string/url)
• bg_color (html color string)
• bg_repeat (css repeat string)
• bg_position (css repeat string)
• has_places (boolean)
• places (array of posts)
• has_section_map (boolean)
• max_listing_posts (integer)
• not_listed (boolean)
• has_top_highlighted
• has_middle_highlighted
• has_bottom_highlighted
• highlighted_top_title
• highlighted_middle
• highlighted_bottom
• highlighted_top
• highlighted_middle_title
• highlighted_bottom_title

Attachment extras:

• video_url (message string)

Place extras:

• location (OpenStreetMaps field)
• is_country (boolean)
• flag (image array)

Follower extras:

• email (string)
• ip (string)
• user_agent (string)
• activated (boolean)
• mail_list (string)

Date ACF fields must have the return format Ymd to be correctly displayed

Add post type

1. Add the post type via admin using CPT plugin
2. Add the translation and path in the wpp_post_type_translations option via WPP option
3. Add the post type endpoint in the wpp_post_type_endpoints option via WPP option
4. Add the new post type in the List post typesin the section fields via Advanced Custom Fields
5. Remove the cache

Admin credentials

• Default username: wppadmin
• Default password: T9y6jGS3C9^7#VvNYXzAMuw#