Installing a local development enviroment

Our goal is to make diving into Municipio development hassle-free, even if the setup process differs significantly from a standard WordPress installation. Here’s a concise guide to get you started:

Prerequisites

Ensure you have the following prerequisites before you proceed:

• Laravel Valet (Mac, Linux, Windows)
  • PHP 7.4 – Set the PHP version
• Local MySQL or MariaDB database server
• Composer
• A copy of ACF PRO
• NPM

Initializing project

Follow these steps to create your local development environment:

1. Navigate to your Laravel Valet base directory for hosts.
2. Run the following command in your root web directory. You might consider forking the repository to your own organization, as explained in the guide “Deploying A Live Environment“. This allows you to manage production installations and updates from this install.

valet tld local.municipio.tech && valet park && mkdir dev && cd dev && valet link && valet secure && valet link dev-a && valet link dev-b && valet link dev-c && valet secure dev-a && valet secure dev-b && valet secure dev-c && git clone git@github.com:municipio-se/municipio-deployment.git . && composer install --prefer-source

The “prefer-source” argument tells the composer install, to fetch everything as repositorys instead of composer packages. This may create warnings on packages not managed by Helsingborg Stad, but the install should proceed anyway.

Add ACF PRO

Integrate ACF PRO into your system by simply dropping your copy of it into the designated plugins directory.

Development domains

For easy database seeding, we recommend using the common development domain (this will be done in above command). This domain will always point to your local environment at 127.0.0.1 or ::1. Below subdomains will point to your installation.

• https://dev.local.municipio.tech/
• https://dev-a.local.municipio.tech/
• https://dev-b.local.municipio.tech/
• https://dev-c.local.municipio.tech/

Configuration

After cloning, you want to configure the project to suit you local development needs.

1. Copy the contents of config-example directory to a new folder named config.
2. Rename and configure *-example.php files within your config directory. At least the database-example.php and salts-example.php is REQUIRED.

This will default to a multisite install. If you like to run this install as a single site (not recommended), you may adjust this in config/multisite.php.

Setup a empty Database

1. Database Creation: Generate a fresh database named “dev” on your local server. This serves as the foundation for your WordPress site.
2. WordPress Setup: Follow the standard WordPress guide for initiating a new website. This involves specifying “dev” as the designated database while configuring your WordPress installation.
3. Alternative Approach: If utilizing the “local.municipio.tech” domain, you can directly proceed to database seeding. Bypass the graphical interface installation and directly move to populating the database with content.

By adhering to these steps, you’ll efficiently establish an empty database for your WordPress site, either through the conventional setup or via the streamlined seeding process if using the specified domain.

Seeding a Database

To seed your database effectively, use the provided SQL file located at db/seed.sql. If necessary, perform a git pull to ensure you have the latest database version. This pre-populated database jumpstarts your development with quality setup and content.

1. Download the latest version using git pull.
2. Run: wp db import ./db/seed.sql

• Note: This will overwrite previous configurations, user accounts, etc. It also resets the user accounts to:
  • superadmin/superadmin ( role: administrator )
  • editor/editor
  • subscriber/subscriber

Building

Before running the build step below you may have to login to the github package registry. This is required to be able to download the styleguide package from github.

Run the following command to log in to the github package registry:

npm login --registry=https://npm.pkg.github.com

Provide a personal access token with package:read privileges as password when prompted while loggin in. If you need help setting up a personal token on GitHub please refer to the documentation on GitHub.

Running the build script

Anticipate a productive coffee break ahead! Before you indulge in your well-deserved cup of coffee, be aware that running the command “php build.php” in the root directory might take some time. This command will efficiently build both the theme and all connected plugins simultaneously, so you can sit back, relax, and enjoy your coffee while the process completes.