# 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.

Node.js
Yarn
Docker
Terminal

You will require at least 2GB of RAM to run Nodewood, so please make sure your Docker "Memory" (under "Resources") is set to at least that, or make sure the system (or VM) that you are running on has at least that much memory available to it.

# Node.js

Node.js (opens new window) is the executable that runs JavaScript programs on your system. Since our package manager (Yarn) is a JavaScript program, we need to have Node.js installed to run it.

# 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

Visit https://yarnpkg.com/getting-started/install (opens new window)
Follow the installation instructions to install yarn from NPM. Skip the "Per-project install" section, as Nodewood still uses Yarn 1.

WARNING

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).

You may also need to add your Yarn global binary folder to your PATH (opens new window), if you get an error like 'nodewood' could not be found or The term 'nodewood' is not recognized.

# 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.

TIP

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 can use an app called Mutagen (opens new window) to SIGNIFICANTLY speed up that mount speed, by double (or more)!

Check out our article titled How To Speed up Docker on MacOS by 100% or more (opens new window) for an explanation of how it works, then how to apply it to your Nodewood project. You'll be glad you did!

# 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:

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.
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.
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.
Change to your new application's folder: cd DIR where DIR is the directory from before.
Run initial database migrations with nodewood migrate.
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.)

TIP

You will need to accept the self-signed certificate to continue, though you will only need to do this once. If you are on Google Chrome, accepting the certificate is a bit... non-standard. You need to visit chrome://flags/#allow-insecure-localhost and change "Allow invalid certificates for resources loaded from localhost." to "Enabled". Alternatively, if you don't want to change settings in your browser, just allow it for the one site, you can click anywhere on the certificate warning page, and then type in "thisisunsafe". This instructs Chrome to accept the "unsafe" self-signed certificate.

Despite the various browser warnings, this poses no actual security risk, 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.

TIP

You may notice the following error on first run:

error  'wood' should be listed in the project's dependencies.

This sometimes occurs on first run. Use Ctrl+C to close and then re-run nodewood dev, and it will go away. Alternatively, you can use lazydocker (opens new window) to restart only the ui container.

# Troubleshooting

← Third-party libraries Filesystem Layout →