Hosting

Building

Generally you will want to setup build (npm) scripts for running Greenwood and other related tasks relevant to your project in your package.json. These can also be configured with the hosting provider of your choice for build time commands.

{
  "scripts": {
    "dev": "greenwood develop",
    "build": "greenwood build",
    "serve": "greenwood serve"
  }
}

By default when running greenwood build, all your build assets will be output into a directory called public/ and will include all your static HTML and assets (JS, CSS, images) as well as code needed for serving dynamic content (SSR pages, API routes).

# hybrid build output example
public/
  api/
    card.bb3e149d.js
    fragment.bb3e149d.js
    fragment.js
  styles
    home.1953429207.css
    theme.663924927.css
  favicon.ico
  index.html
  modal.edbd7922.js
  products.route.chunk.b012f9ed.js
  products.route.js

Static Hosting

By default deploying a static site should not require anything other than making sure you are using the contents output to the build directory. As the name implies, static hosting does not support SSR pages (unless statically exported) or API routes, but read on to learn more about those options.

Self Hosting

You can of course run your Greenwood application anywhere you can install NodeJS. The recommended way to do so is by following these steps:

1. Build your application with greenwood build
2. Upload / Copy the contents of the public/ directory onto your webserver / webroot
3. Run npx @greenwood/cli serve from your webroot
4. Forward traffic to the server running at localhost:8080 (default port is 8080)

Serverless

For deploying SSR pages and API routes to serverless hosting providers, you can use (or create your own) adapter plugins like for Vercel or Netlify.

You can see our docs on adapter plugins to learn more about creating (or contributing!) your own.

Docker

Docker is a widely supported developer tool for standardizing the deployment pipeline for applications. You can easily adapt the baseline NodeJS Docker image and fine-tune it for Greenwood with just a couple steps. We have a demo repo that you can clone or fork and customize to your needs.

These steps are based on a Greenwood application generated by @greenwood/init and then having the docker init command run with these options.

? What application platform does your project use? Node (auto detected)
? What version of Node do you want to use? 18.20.2 (auto detected)
? Which package manager do you want to use? npm (auto detected)
? Do you want to run "npm run build" before starting your server? Yes (auto detected)
? What directory is your build output to? (comma-separate if multiple) public
? What command do you want to use to start the app? npm run serve
? What port does your server listen on? 8080

1. Add **/.greenwood to .dockerignore

2. If using npm, make sure to mount the .npmrc file in both the deps and build stages, e.g.

   RUN --mount=type=bind,source=package.json,target=package.json \
       --mount=type=bind,source=package-lock.json,target=package-lock.json \
       --mount=type=cache,target=/root/.npm \
       --mount=type=bind,source=.npmrc,target=.npmrc \
       npm ci --omit=dev
   

3. Install the @greenwood/cli in the deps stage, e.g.

   RUN --mount=type=bind,source=package.json,target=package.json \
       --mount=type=bind,source=package-lock.json,target=package-lock.json \
       --mount=type=bind,source=.npmrc,target=.npmrc \
       --mount=type=cache,target=/root/.npm \
       npm ci --omit=dev
   
   # add this line
   RUN npm i @greenwood/cli@latest
   

4. Copy the .greenwood/ directory into the container

   COPY --from=deps /usr/src/app/node_modules ./node_modules
   COPY --from=build /usr/src/app/public ./public
   # add this line
   COPY --from=build /usr/src/app/.greenwood ./.greenwood
   

5. Run the serve command

   CMD npm run serve
   

Many self-hosting solutions support Docker, like our demo repo using Fly.io.