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
- WordPress
- PHP
- php-mbstring
- roots/sage: WordPress starter theme with a modern development workflow
- Sage 9.x: Installation | Roots Documentation
- Composer
- Node.js
- Yarn
- Make sure all dependencies have been installed before moving on:
WordPress >= 4.7
-
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.
- If you installed WordPress in the root directory, you should visit: http://example.com/
- If you installed WordPress in its own subdirectory called blog, for example, you should visit: http://example.com/blog/
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
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
--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
Node.js and npm packages are available in the Community Repository.
pacman -S nodejs npm
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.
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.
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
- If the environment variable
$XDG_CONFIG_HOME
is present, it will place thenvm
files there. - You can add
--no-use
to the end of the above script (...nvm.sh --no-use
) to postpone usingnvm
until you manuallyuse
it. - You can customize the install source, directory, profile, and version using the
NVM_SOURCE
,NVM_DIR
,PROFILE
, andNODE_VERSION
variables. Eg:curl ... | NVM_DIR="path/to/nvm"
. Ensure that theNVM_DIR
does not contain a trailing slash. - The installer can use
git
,curl
, orwget
to downloadnvm
, whichever is available.
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
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.
- Add this to your profile:
export PATH="$PATH:/opt/yarn-[version]/bin"
(the path may vary depending on where you extracted Yarn to) - 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.
- 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
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.
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.
- Add this to your profile:
export PATH="$PATH:/opt/yarn-[version]/bin"
(the path may vary depending on where you extracted Yarn to) - 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
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 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.
- Update
devUrl
at the bottom ofresources/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",
...
-
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.
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;
}
- 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>