Deploy a static site

This tutorial serves a static site from a GitHub repository with the Static site build type: HTML, CSS, images and scripts served as files, with no server of your own.

You need a GitHub repository holding the site's files as they should be served, with an index.html at the top of the site. The tutorial uses this layout:

• index.html
• about.html
• assets

  • site.css

Cloud sends a Static site build no install or build command: the console offers those fields for nixpacks only. This tutorial covers files that are served as they are in the repository.

You also need a project to put the service in, and GitHub connected under Settings, Git providers. Deploy from GitHub covers the connection.

1. Open the GitHub form

   On the project, press Add a service, then Create on Git repository (GitHub App).

2. Choose the repository

   Choose the Account, the Repository and the Branch. Cloud reads the top of the repository and, finding an index.html and no package.json, Dockerfile or railpack.json, sets Build with to Static site, with the line "From the repository: an index.html and nothing to build."

   If the repository also holds a package.json, Cloud chooses nixpacks instead. Set Build with to Static site yourself.

3. Create it

   Name the service, such as site, choose a Size, and press Create service. The service's page opens.

On the service's Overview, two fields of the Source card decide which files are served:

For the layout above, leave both empty: the site is at the root of the repository, which is where Cloud found index.html.

When the site sits lower down, name its directory:

• The whole site in public/: set Publish directory to public.

• A site in sites/docs/ of a larger repository: set Build path to sites/docs, and Publish directory to the directory under it that holds the files, if any.

Publish directory is counted from the build path, so dist, /dist and dist/ are the same directory, and a path with .. in it is refused. Press Save source after a change.

Press Deploy in the service's header. The deployment's page opens with its Build log, and the status ends Done once the site's container is running. At that first Done deployment, Cloud gives the service an address on the platform's domain, which its Domains section shows until it reads HTTPS active.

Press Visit in the service's header once it is available. If your page answers, the site is live.

If the address answers with an error page while the deployment reads Done, the port is the likely cause. Cloud sends a domain's traffic to the service's Port, which is 3000 unless you change it on the Settings section, and it does not set the port for a Static site build. To find the port the site's server listens on, open Terminal, pick the service, and list the ports inside the container, for example with netstat -tln where the image carries it.

Then:

1. Set the port

   On the Settings section, set Port to that port and press Save settings.

2. Replace the address

   The generated address keeps the port the service had when it was made. On the Domains section, remove it with the bin button labelled "Remove domain".

3. Deploy again

   Press Deploy. The next Done deployment generates a new address that uses the new port.

Domains explains why the address does not follow the port.

Each push to the branch deploys the site again, unless you set Deploy on to Only when I ask on the Source card. A push that arrives while a deployment is still running is dropped, not queued. Source and deploy triggers covers both, and watch paths for a site that shares its repository with other code.

To serve the site on your own hostname, add it with Add domain and create the records Show DNS records lists. Domains walks through it.