Skip to content

Instantly share code, notes, and snippets.

Embed
What would you like to do?
Awesome poet - a WordPress plugin

Awesome Log1x/poet

I was recommended to contribute to this project by GitHub. I want to test to see if the recommendations are actually good to what I should be doing, or if it is just kind of random based on what it thinks I'm interested in

I would recommend checking that the methods I have used in this document have not changed since I wrote this. I put this together for convenience sake, and may not update it in a timely manor

Requirements

Installation

  • Make sure all dependencies have been installed before moving on:

WordPress >= 4.7

  • How to install WordPress | WordPress.org

  • Download and unzip the WordPress package if you haven’t already.

  • Create a database for WordPress on your web server, as well as a MySQL (or MariaDB) user who has all privileges for accessing and modifying it.

  • (Optional) Find and rename wp-config-sample.php to wp-config.php, then edit the file (see Editing wp-config.php) and add your database information. Note: If you are not comfortable with renaming files, step 3 is optional and you can skip it as the install program will create the wp-config.php file for you.

  • Upload the WordPress files to the desired location on your web server:

    • If you want to integrate WordPress into the root of your domain (e.g. http://example.com/), move or upload all contents of the unzipped WordPress directory (excluding the WordPress directory itself) into the root directory of your web server.
    • If you want to have your WordPress installation in its own subdirectory on your website (e.g. http://example.com/blog/), create the blog directory on your server and upload the contents of the unzipped WordPress package to the directory via FTP.
    • Note: If your FTP client has an option to convert file names to lower case, make sure it’s disabled.
  • Run the WordPress installation script by accessing the URL in a web browser. This should be the URL where you uploaded the WordPress files.

That’s it! WordPress should now be installed.

PHP >= 7.1.3 (with php-mbstring enabled)

There are a few pre-packaged and pre-compiled versions of PHP for macOS. This can help in setting up a standard configuration, but if you need to have a different set of features (such as a secure server, or a different database driver), you may need to build PHP and/or your web server yourself. If you are unfamiliar with building and compiling your own software, it's worth checking whether somebody has already built a packaged version of PHP with the features you need.

The quickest way to install php on macOS is with homebrew:

  • install homebrew, by following the instructions at » brew.sh or
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
  • install php
brew install php

PHP has a tonne of alternatives, I suggest researching and deciding what you like best and the topic I recommend researching is LAMP, LEMP, or WAMP

Composer

Command-line installation

To quickly install Composer in the current directory, run the following script in your terminal. To automate the installation, use the guide on installing Composer programmatically.

php -r "copy('https://getcomposer.org/installer', 'composer-setup.php');" php -r "if (hash_file('sha384', 'composer-setup.php') === '756890a4488ce9024fc62c56153228907f1545c228516cbf63f885e036d37e9a59d27d63f46af1d4d07ee0f76181c7d3') { echo 'Installer verified'; } else { echo 'Installer corrupt'; unlink('composer-setup.php'); } echo PHP_EOL;" php composer-setup.php php -r "unlink('composer-setup.php');"

This installer script will simply check some php.ini settings, warn you if they are set incorrectly, and then download the latest composer.phar in the current directory. The 4 lines above will, in order:

  • Download the installer to the current directory
  • Verify the installer SHA-384, which you can also cross-check here
  • Run the installer
  • Remove the installer

Most likely, you want to put the composer.phar into a directory on your PATH, so you can simply call composer from any directory (Global install), using for example:

sudo mv composer.phar /usr/local/bin/composer
Notable Installer Options

--install-dir

You can install composer to a specific directory by using the --install-dir option and providing a target directory. Example:

php composer-setup.php --install-dir=bin

--filename

You can specify the filename (default: composer.phar) using the --filename option. Example:

php composer-setup.php --filename=composer

--version

You can install composer to a specific release by using the --version option and providing a target release. Example:

php composer-setup.php --version=1.0.0-alpha8

--help

The installer provides more options for specific environments, use the --help option to see all of them.

Node.js >= 8.0.0

I'm in the habit of using nvm

Arch Linux

Node.js and npm packages are available in the Community Repository.

pacman -S nodejs npm

CentOS, Fedora and Red Hat Enterprise Linux

Node.js is available as a module called nodejs in CentOS/RHEL 8 and Fedora.

dnf module install nodejs:<stream>

where <stream> corresponds to the major version of Node.js. To see a list of available streams:

dnf module list nodejs

For example, to install Node.js 12:

dnf module install nodejs:12

For CentOS/RHEL 7 Node.js is available via Software Collections.

fnm (Debian and Ubuntu)

Fast and simple Node.js version manager built in Rust used to manage multiple released Node.js versions. It allows you to perform operations like install, uninstall, switch Node versions automatically based on the current directory, etc. To install fnm, use this install script.

fnm has cross-platform support (macOS, Windows, Linux) & all poplar shells (Bash, Zsh, Fish, PowerShell, Windows Command Line Prompt) it's built with speed in mind and compatibility support for .node-version and .nvmrc files.

nvm (my favorite)

Installing and Updating

To install or update nvm, you should run the install script. To do that, you may either download and run the script manually, or use the following cURL or Wget command:

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.38.0/install.sh | bash
wget -qO- https://raw.githubusercontent.com/nvm-sh/nvm/v0.38.0/install.sh | bash

Running either of the above commands downloads a script and runs it. The script clones the nvm repository to ~/.nvm, and attempts to add the source lines from the snippet below to the correct profile file (~/.bash_profile, ~/.zshrc, ~/.profile, or ~/.bashrc).

export NVM_DIR="$([ -z "${XDG_CONFIG_HOME-}" ] && printf %s "${HOME}/.nvm" || printf %s "${XDG_CONFIG_HOME}/nvm")"
[ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh" # This loads nvm
Additional Notes
  • If the environment variable $XDG_CONFIG_HOME is present, it will place the nvm files there.
  • You can add --no-use to the end of the above script (...nvm.sh --no-use) to postpone using nvm until you manually use it.
  • You can customize the install source, directory, profile, and version using the NVM_SOURCE, NVM_DIR, PROFILE, and NODE_VERSION variables. Eg: curl ... | NVM_DIR="path/to/nvm". Ensure that the NVM_DIR does not contain a trailing slash.
  • The installer can use git, curl, or wget to download nvm, whichever is available.
Troubleshooting on Linux

On Linux, after running the install script, if you get nvm: command not found or see no feedback from your terminal after you type command -v nvm, simply close your current terminal, open a new terminal, and try verifying again. Alternatively, you can run run the following commands for the different shells on the command line:

bash: source ~/.bashrc

zsh: source ~/.zshrc

Yarn

Before you start using Yarn, you'll first need to install it on your system. There are many different ways to install Yarn, but a single one is recommended and cross-platform:

  • Install via npm

It is recommended to install Yarn through the npm package manager, which comes bundled with Node.js when you install it on your system.

Once you have npm installed you can run the following both to install and upgrade Yarn:

npm install --global yarn
  • Installation Script

One of the easiest ways to install Yarn on macOS and generic Unix environments is via our shell script. You can install Yarn by running the following code in your terminal:

curl -o- -L https://yarnpkg.com/install.sh | bash
  • Manual Install via tarball

You can install Yarn by downloading a tarball and extracting it anywhere.

cd /opt
wget https://yarnpkg.com/latest.tar.gz
tar zvxf latest.tar.gz
# Yarn is now in /opt/yarn-[version]/

If Yarn is not found in your PATH, follow these steps to add it and allow it to be run from anywhere.

Note: your profile may be in your .profile, .bash_profile, .bashrc, .zshrc, etc.

  1. Add this to your profile: export PATH="$PATH:/opt/yarn-[version]/bin" (the path may vary depending on where you extracted Yarn to)
  2. In the terminal, log in and log out for the changes to take effect

To have access to Yarn’s executables globally, you will need to set up the PATH environment variable in your terminal. To do this, add export PATH="$PATH:`yarn global bin`" to your profile, or if you use Fish shell, simply run the command set -U fish_user_paths (yarn global bin) $fish_user_paths

  • Arch Linux

On Arch Linux, Yarn can be installed through the official package manager.

pacman -S yarn
  • CentOS / Fedora / RHEL

On CentOS, Fedora and RHEL, you can install Yarn via our RPM package repository.

curl --silent --location https://dl.yarnpkg.com/rpm/yarn.repo | sudo tee /etc/yum.repos.d/yarn.repo

If you do not already have Node.js installed, you should also configure the NodeSource repository:

curl --silent --location https://rpm.nodesource.com/setup_12.x | sudo bash -

Then you can simply:

sudo yum install yarn
## OR ##
sudo dnf install yarn
  • Debian / Ubuntu

On Debian or Ubuntu Linux, you can install Yarn via our Debian package repository. You will first need to configure the repository:

curl -sS https://dl.yarnpkg.com/debian/pubkey.gpg | sudo apt-key add -
echo "deb https://dl.yarnpkg.com/debian/ stable main" | sudo tee /etc/apt/sources.list.d/yarn.list

On Ubuntu 16.04 or below and Debian Stable, you will also need to configure the NodeSource repository to get a new enough version of Node.js.

Then you can simply:

sudo apt update && sudo apt install yarn

Note: Ubuntu 17.04 comes with cmdtest installed by default. If you’re getting errors from installing yarn, you may want to run sudo apt remove cmdtest first. Refer to this for more information.

If using nvm you can avoid the node installation by doing:

sudo apt update && sudo apt install --no-install-recommends yarn

Note: Due to the use of nodejs instead of node name in some distros, yarn might complain about node not being installed. A workaround for this is to add an alias in your .bashrc file, like so: alias node=nodejs. This will point yarn to whatever version of node you decide to use.

  • macOS (and Linux with Linuxbrew)

You can install Yarn through the Homebrew package manager. This will also install Node.js if it is not already installed.

brew install yarn

If you use nvm or similar, you should ensure that your PATH lists nvm’s shims before the version of Node.js installed by Homebrew.

  • Windows (There are three options for installing Yarn on Windows.)

Download the installer

This will give you a .msi file that when run will walk you through installing Yarn on Windows.

If you use the installer you will first need to install Node.js.

Download Installer

  • Install via Chocolatey

Chocolatey is a package manager for Windows. You can install Chocolatey by following these instructions.

Once you have Chocolatey installed, you may install yarn by running the following code in your console:

choco install yarn

This will also ensure that you have Node.js installed.

  • Install via Scoop

Scoop is a command-line installer for Windows. You can install Scoop by following these instructions.

Once you have Scoop installed, you may install yarn by running the following code in your console:

scoop install yarn

If Node.js is not installed, scoop will give you a suggestion to install it. Example:

scoop install nodejs

Notice

Please whitelist your project folder and the Yarn cache directory (%LocalAppData%\Yarn) in your antivirus software, otherwise installing packages will be significantly slower as every single file will be scanned as it’s written to disk.

Path Setup

Unix/Linux/macOS

If Yarn is not found in your PATH, follow these steps to add it and allow it to be run from anywhere.

Note: your profile may be in your .profile, .bash_profile, .bashrc, .zshrc, etc.

  1. Add this to your profile: export PATH="$PATH:/opt/yarn-[version]/bin" (the path may vary depending on where you extracted Yarn to)
  2. In the terminal, log in and log out for the changes to take effect

To have access to Yarn’s executables globally, you will need to set up the PATH environment variable in your terminal. To do this, add export PATH="$PATH:`yarn global bin`" to your profile, or if you use Fish shell, simply run the command set -U fish_user_paths (yarn global bin) $fish_user_paths

Windows

You will need to set up the PATH environment variable in your terminal to have access to Yarn’s binaries globally.

Add set PATH=%PATH%;C:\.yarn\bin to your shell environment.

Check installation

Check that Yarn is installed by running:

yarn --version
  • Install Sage using Composer from your WordPress themes directory (replace your-theme-name below with the name of your theme):
# @ app/themes/ or wp-content/themes/
composer create-project roots/sage your-theme-name
  • You will have the option to define theme meta information (name, URI, description, version, author) and choose a CSS framework
  • From the command line on your host machine (not on your Vagrant box), navigate to the theme directory then run yarn:
# @ themes/your-theme-name/
$ yarn
  • You now have all the necessary dependencies to run the build process.

Browsersync configuration

  • Update devUrl at the bottom of resources/assets/config.json to reflect your local development hostname.
  • For example, if your local development URL is https://project-name.test you would update the file to read:
...
  "devUrl": "https://project-name.test",
...

Server configuration

  • Sage uses Laravel's Blade templating engine, and since the .blade.php files live in a publicly accessible directory on your webserver, we recommend preventing plain-text access to them.

  • Sage uses composer and yarn to manage dependencies, and since their files might contain private credentials and expose dependency versions, we recommend blocking them as well.

Nginx configuration for denying access to Blade, composer and yarn files

Add to your server block before the final location directive:

location ~* \.(blade\.php)$ {
  deny all;
}

location ~* composer\.(json|lock)$ {
  deny all;
}

location ~* package(-lock)?\.json$ {
  deny all;
}

location ~* yarn\.lock$ {
  deny all;
}

Apache configuration for denying access to Blade files

  • Add to your .htaccess file or virtual host configuration:
<FilesMatch ".+\.(blade\.php)$">
    <IfModule mod_authz_core.c>
        # Apache 2.4
        Require all denied
    </IfModule>
    <IfModule !mod_authz_core.c>
        # Apache 2.2
        Order deny,allow
        Deny from all
    </IfModule>
</FilesMatch>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment