Skip to content

Hosting: deployments, logs and environment variables

With Hosting, EcomWeb builds your storefront code and runs it on your store’s domain. The Hosting page shows which build the site runs, every build of the store with its log, and the environment variables your code needs.

Switching to a build, previewing it or changing it is done on each theme’s own page. The Hosting page is shared by all the themes of the store. To deploy code, see Edit a theme’s code and deploy it.

  1. In the sidebar, click Online Store.
  2. Click Hosting, just under Online Store.

On a phone, tap the menu icon at the top left to open the sidebar.

If the plan has no Hosting, the page shows Your plan doesn’t include hosting and an Upgrade plan button. If Hosting is switched off on the EcomWeb platform, it shows Hosting isn’t on. That setting covers every store, so contact EcomWeb. Ready-made and Self-hosted themes still work in both cases.

The Hosted storefront card shows the state of the site on your store’s domain.

State Meaning
Not live EcomWeb is not running your code on the store’s domain.
Rolling out A new build is being put live. The previous one keeps serving customers until the new one is ready.
Live The site is running.
Down The site has a problem. Read the log of the build that is showing.

When a build is running, the card shows its theme and build id. If the last rollout failed, the card says that the store kept its previous version and shows the details. The Usage card shows the previews running now and the build time used this month.

  1. In the All builds card, find the build by its id or its theme.
  2. Click Build log on its row.
  3. Read the log in the card that opens under the list.
  4. Click Close to close it.

The log of a build that is still running updates until the build ends. A failed build shows Build failed in its status.

You can read the same information from the CLI.

Terminal window
# List the store's builds
ecomweb deployments
# Print a build's log and follow it until it ends
ecomweb logs <build id>

ecomweb logs exits with code 5 if the build failed. In the Store API, a key needs one of these scopes:

  • deploy:storefront to list and read builds and their logs, and to deploy and promote them. A key with only admin:store cannot read them.
  • admin:store to list, set and delete environment variables, and to rotate the forwarder secret. A key with only deploy:storefront cannot do these.

Environment variables hold the values your code needs but that should not be in the repository, such as a payment key or an analytics id.

  1. In the Environment variables card, enter the Name, for example STRIPE_SECRET_KEY.
  2. Enter the Value.
  3. If the code needs the variable while it is built, select Build time (NEXT_PUBLIC_ only).
  4. Click Save variable.

The value is encrypted and never shown again. The list shows only names, with the label Runtime or Build time. A value can be at most 4 KB, and a store can have at most 50 variables.

  • A runtime variable applies to the site and to previews. They restart when the variable changes.
  • A build-time variable must start with NEXT_PUBLIC_. It applies from the next build that EcomWeb runs. Builds that run somewhere else, such as a prebuilt upload or a deploy on push, do not get it, so set the value in the environment of that build.
Rule Detail
Characters Upper case letters, digits and _, starting with a letter
Length At most 64 characters
Reserved Names starting with ECOMWEB_ or CLIENT_IP_, and SITE_URL, NODE_ENV, PORT and HOSTNAME belong to EcomWeb and cannot be set
Build time The name must start with NEXT_PUBLIC_. The value cannot contain both ' and a backtick, or control characters other than a newline and a tab

From the CLI:

Terminal window
# Set a runtime variable, reading the value from stdin so it stays out of your shell history
printf %s "$STRIPE_SECRET" | ecomweb env set STRIPE_SECRET --stdin
# Set a build-time variable
ecomweb env set NEXT_PUBLIC_GA_ID=<id> --build
# List the variable names
ecomweb env

Setting variables from the CLI or the API needs a key with the admin:store scope.

  1. In the Environment variables card, click Delete on the variable’s row.
  2. Confirm with Delete.

Deleting a runtime variable restarts the site and previews without it. A build-time variable is gone from the next build.

Terminal window
ecomweb env unset STRIPE_SECRET

The GitHub repository card creates a repository on your own GitHub account, with the site’s code and ready to clone. A store has one GitHub connection and one repository.

  1. Click Connect GitHub.
  2. Install the EcomWeb app on GitHub, following the steps GitHub shows.
  3. Back on the Hosting page, enter the Repository name.
  4. In Deploy to theme, choose the theme that receives the builds from this repository.
  5. Leave Private repository on unless the code can be public.
  6. Click Create repository.

When the repository is ready, the card Your storefront code is ready shows its address and the commands to clone it and run it. You can do the same from the CLI with ecomweb storefront init --github.

Hosting is switched off on the EcomWeb platform, not for your store alone. Contact EcomWeb. Meanwhile, ready-made themes and self-hosted sites still work.

My plan no longer includes Hosting. Do I lose my builds?

Section titled “My plan no longer includes Hosting. Do I lose my builds?”

No. Builds and environment variables are kept. Customers see the theme’s ready-made version, and you cannot deploy or set new variables until you upgrade.

What do customers see if a deploy to the live theme fails?

Section titled “What do customers see if a deploy to the live theme fails?”

The store keeps serving the previous version. The Hosted storefront card says the last rollout failed and shows the details.