# Installation

First, make sure you have installed the requirements for running Nodewood, then follow the instructions to create a new Nodewood project.

# Requirements

Nodewood relies on a collection of tools in order to simplify and speed up development. This section of the guide will explain those tools and how to install them on your system.

# Yarn

Yarn is an alternative package manager to NPM. For the most part, they are interchangeable, but Nodewood uses Yarn to set up workspaces (opens new window). This allows Nodewood to specify packages it uses in its own package.json file, and your app to specify packages it uses in its own package.json file. This makes it easier to update Nodewood packages without clobbering your application's packages. (i.e. if Nodewood stops using a package that your package continues to use, Nodewood removing it from its own package.json won't break your application).

# Installation

  1. Visit https://yarnpkg.com/getting-started/install (opens new window)
  2. Follow the installation instructions to install yarn from NPM.


If you are installing Yarn on Windows, you must restart your computer after installation, otherwise globally-installed yarn modules (like the Nodewood CLI!) won't work. This is a reported Yarn issue (opens new window).

# Docker

Docker is a tool that allows for the packaging of software applications into lightweight containers, and then running those containers in a reasonably low-effort way. Nodewood uses a small collection of Docker containers during development to run a PostgreSQL database and Nginx web server, as well as watchers for the Express API and Webpack UI portions of Nodewood itself. Using Docker means you don't need to manually set up PostgreSQL and Nginx, and you don't need to have multiple terminal windows open to monitor the API and UI processes separately.

# Installation

Installing Docker is thankfully reasonably easy and well-documented. Choose your installation instructions based on your operating system:

You will also need to create an account on Docker Hub (opens new window) and then sign in on Docker Desktop. If you find that Docker is abruptly halting while launching the Nodewood containers, it is likely because you are not signed in and it cannot find your authorization information.

If you are not yet familiar with Docker, Docker for beginners (opens new window) can help you get comfortable with the basics, however I would appreciate feedback about what aspects cause problems, so that I can improve them or write documentation to help.


If you are running on OSX, you might find Docker's performance a bit... poky. This is because the default volume mount (i.e. how your project folder is mounted inside the Docker container) is slow. Thankfully, we stand on the shoulders of giants, and Jeff Geerling has gone ahead and figured out how to use NFS to mount to the local system and speed Docker up significantly (opens new window).

If you are making any changes to your Docker configuration, first make sure to copy the entire wood/docker folder into app/docker and then make your changes there, otherwise any upgrade to your Nodewood version could see your changes get overwritten!

# Terminal

The default terminal for your system may make your life more difficult than it has to be. For example, the default Windows terminal requires you to right-click and select "Paste" to copy and paste -- your expected keyboard commands won't work. Here are a list of alternative terminals that will improve your development experience:

# Windows: Windows Terminal

Microsoft helpfully provides Windows Terminal (opens new window) for free on the Microsoft Store. It adds tabs, starts you off with a sane font size, and has working keyboard shortcuts for copy/paste.

# OSX: iTerm2

iTerm2 (opens new window) is jam-packed with a variety of improved features (opens new window) over the default OSX terminal. Of particular note is the ability to bind a system-wide hotkey that will bring the terminal to the forefront, for instant access.

# Linux: You probably have a favourite terminal already

Oh no, I'm not getting into this fight. There are dozens of really great terminal emulators for Linux, and the default installed with your OS is likely already more than sufficient for a really great experience. You're already a winner.

# Create a new Nodewood Project

New projects are created with the Nodewood CLI tool. To install or update the tool:

yarn global add @nodewood/cli

After, follow these steps to create and spin up a new Nodewood project:

  1. Log in at Nodewood (opens new window) and click on "Projects" in the sidebar. Click the "New Project" button, enter a project name, and click "Create". Copy the API Key and Secret Key returned to you.
  2. Run nodewood new DIR where DIR is the directory in which you want to create your app. Paste in your API Key and Secret Key when asked. Let it download and extract files, and run the installers.
  3. Set up your mailer. This is optional, but can make your life easier. If you don't set up a mailer now, emails will be logged to your terminal, and links for account activation/password reset can be copied from there.
  4. Change to your new application's folder: cd DIR where DIR is the directory from before.
  5. Run initial database migrations with nodewood migrate.
  6. Run the Nodewood development server with nodewood dev.

This will start a PostgreSQL instance, an Nginx instance, the API Express server, and the Webpack UI process. It can take a while for all these processes to start up, but the UI process is usually the last one to complete. You'll be able to tell when you see the following UI log line:
ui_1        |  DONE  Build complete. Watching for changes...

Provided you are not currently running a webserver on your host machine, you can now access your Nodewood project at https://localhost (opens new window). (If you are running a webserver on your host machine, you can either halt it while developing your Nodewood project, or alter the ports entry in the nginx section in docker-compose.yml.) You will need to accept the self-signed certificate to continue, though you will only need to do this once. (This poses no actual security risk, despite any browser warnings, since it is only a development application, and one under your control.)

Both the API and the UI will watch for changes as you develop, and will restart/recompile accordingly. You will need to give it a few seconds after you save your changes, but never especially long. You can always check back on your terminal window to see if the restart/recompile has completed.

Every process logs to the same window, which might be confusing at first, but each line is prefixed by what process caused it, and coloured uniquely, which should help reduce confusion.