Skip to content

INSTALLATION.md

Latest commit

 

History

History
295 lines (227 loc) · 9.91 KB

INSTALLATION.md

File metadata and controls

295 lines (227 loc) · 9.91 KB

Dekode Project Base - Installation Guide

Table of Contents

Requirements

Project Structure

  • Packages: Contains all project-specific code such as plugins, themes, mu-plugins, and custom libraries. These are built into the public directory using symlinks via Composer.
  • Public: Contains files used by WordPress, automatically generated from packages by Composer. This folder should not be modified manually.
  • Tools: Contains build and setup scripts used by Codeship and Local.
  • Config: Contains environment variable setup files.

Local Setup

Initial Setup

  1. Create a Git Repository:

    • If setting up a new project, create a git repository using Project Base as the template.

  2. Create a New Site in Local:

    • Enable multisite (subdirectory) if applicable to the project.

Setup Methods

Method 1: Replicating Server Structure

  1. Navigate to the app folder:

    cd app

  2. Remove the default public folder:

    rm -rf public

  3. Clone the project into the current folder:

    git clone git@github.com:DekodeInteraktiv/{YOUR_PROJECT} .

  4. Copy the environment example file:

    cp .env.example .env

  5. Update environment variables in the .env file:

    • DB_NAME, DB_USER, DB_PASSWORD, DB_HOST
    • WP_ENVIRONMENT_TYPE (local, development, staging, production)
    • WP_HOME (e.g., http://example.com)
    • WP_SITEURL (e.g., http://example.com/wp)
    • AUTH_KEY, SECURE_AUTH_KEY, LOGGED_IN_KEY, NONCE_KEY, AUTH_SALT, SECURE_AUTH_SALT, LOGGED_IN_SALT, NONCE_SALT

  6. Generate security keys (optional, requires wp-cli):

    wp package install aaemnnosttv/wp-cli-dotenv-command
wp dotenv salts regenerate

    Or use the Roots WordPress Salt Generator.

  7. Install Composer dependencies:

    composer install

  8. Install npm dependencies:

    npm ci

  9. Run local setup scripts (ensure MYSQLI_DEFAULT_SOCKET is set if needed):

    cd app/tools/local
./setup-main-site.sh
./activate-plugins.sh
bash multisite.sh  # Only for multisite setup

  10. Update URLs for multisite to use HTTPS:

    wp search-replace --url=http://{PROJECT}.site 'http://{PROJECT}.site' 'https://{PROJECT}.site' --recurse-objects --network --skip-columns=guid

Method 2: Using Local Structure (Symlink Method)

  1. Navigate to the site app folder and clone the project:

    cd path/to/app
git clone git@github.com:DekodeInteraktiv/{YOUR_PROJECT} .

  2. Remove the default wp-content folder:

    rm -rf public/wp-content

  3. Create a symlink for wp-content:

    ln -s ../{project folder}/public/content public/wp-content

  4. Run local setup scripts:

    cd tools/local
./setup-main-site.sh
./activate-plugins.sh
bash multisite.sh  # Only for multisite setup
Using wp-cli with Local

To use wp-cli with Local, you can use the built-in site shell. For default system console access, add a wp-cli.local.yml file to the root (app) directory:

path: public/wp
require:
  - wp-cli-local.php

Set the MYSQLI_DEFAULT_SOCKET in the .env file using the path from the Local Database tab.

Method 3: Setup with wp-env

  1. Start the Environment
npm wp-env start

This command will spin up a local WordPress environment using Docker.

  1. Scripts
  • start: bash npm run wp-env start Starts the wp-env environment.
  • stop: bash npm run wp-env stop Stops the wp-env environment.
  • clean: bash npm run wp-env clean Removes all WordPress data and resets the environment.
  • destroy: bash npm run wp-env destroy Destroys the wp-env environment.
  • logs: bash npm run wp-env logs Displays logs from the wp-env environment.
  • shell: bash npm run wp-env run cli bash Opens a shell in the wp-env environment.
  • cli: bash npm run wp-env run cli <command> Runs a command in the wp-env environment.
  1. Overriding .wp-env.json with a Local Setup

To customize your local environment without changing the main .wp-env.json, create a .wp-env.override.json file in your project root. For example:

{
	"core": "WordPress/WordPress#6.5",
	"plugins": [ "./my-custom-plugin" ],
	"mappings": {
		"wp-content/uploads": "./uploads"
	}
}

This file will override or extend the default configuration.

  1. Dependencies
  • Docker: Required to run the environment containers.

Installation and Build

Run the following commands in the root directory to build the project:

composer install
npm ci && npm run build

(See packages/themes/block-theme for more details)

BrowserSync for Live Reloading

BrowserSync is included in this project to enable live reloading and synchronized browser testing during development.

Configuration

BrowserSync is configured via browsersync.config.js and uses environment variables from your .env file:

  • BROWSER_SYNC_HTTPS: Set to true to enable HTTPS (default: false).
  • BROWSER_SYNC_PORT: Port for BrowserSync to run on (default: 3002).
  • BROWSER_SYNC_PROXY: The local domain to proxy (defaults to WP_HOME from .env).

Example .env settings:

BROWSER_SYNC_HTTPS=true
BROWSER_SYNC_PORT=3002
BROWSER_SYNC_PROXY=your-local-site.test

Usage

To start BrowserSync, run:

npm run start-sync

This will watch for changes in CSS, JS, and theme.json files inside packages/, and automatically reload your browser.

Note: Make sure your local site is running and accessible at the proxy URL.

Customization

You can modify browsersync.config.js to change watched files or other BrowserSync options as needed.

Extending Builds

Project Base uses wp-scripts out of the box for building front-end/view and editor assets. wp-script will scan all block.json files in the src/ folder to find available entries. This means that if you have a src folder with a view.js and a editor.js, you also need to add a block.json file at the same location. Have a look in the block-theme theme for example or read up on wp-script auto discovery for Webpack entry points. For a more advanced setup, you can always customize builds by adding your own webpack.config.js.

A quick overview of wp-scripts auto discovery:

  1. Supply entry points manully to the CLI, e.g. wp-scripts build src/view src/editor src/admin src/some-other-entry. This will bypass 2 and 3.
  2. Scan src folder for all block.json files. (Our default setup). This will support both theme/plugin assets (view/editor) and possible blocks inside the src/ folder.
  3. Fallback to src/index.* file. This will only look for a src/index.js file.

Adding a new package (plugin, mu-plugin or theme)

  1. Create a folder: Add a folder in ./packages (e.g., ./packages/plugins).

  2. Add a composer.json File (for themes, plugins, mu-plugins, and PHP dependencies):

    {
  "name": "project/package-name",
  "description": "Short description of the package.",
  "type": "wordpress-plugin/wordpress-muplugin/wordpress-theme/other",
  "version": "1.0.0"
}

    Note: Use block-base for Gutenberg blocks.

    Note: A version should always be supplied. This ensures that package versions do not change between branches, leading to unneccesary merge conflicts.

  3. Add a package.json File (for frontend dependencies or custom React components):

    {
  "name": "package-name",
  "private": true,
  "version": "1.0.0",
  "description": "Package description",
  "author": "Dekode",
  "main": "index.js",
  "scripts": {
    "build": "echo \"Error: no build specified\" && exit 1",
    "start": "echo \"Error: no start specified\" && exit 1",
    "test": "echo \"Error: no test specified\" && exit 1",
    "clean": "rm -rf node_modules build dist"
  }
}

  4. Update Root Configuration:

    • For Composer packages, add an entry under "require" in composer.json: 
      "project/package-name": "@dev"
    • For npm packages, add an entry under "devDependencies" in package.json: 
      "package-name": "file:packages/folder/package-name"

  5. Install the Package:

    • For Composer: 
      composer update
    • For npm: 
      npm install

    Re-run npm run build or npm run start if needed.

Additional Documentation