> For the complete documentation index, see [llms.txt](https://prodocs.webhash.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://prodocs.webhash.com/deploying-a-site.md). # Deploying a Site This guide walks you through deploying a GitHub repository to IPFS with WebHash Pro, step by step. By the end you'll have a live site with its own gateway link and content ID (CID). If you haven't signed in yet, head to and sign in with GitHub first. {% hint style="info" %} **What "deploying to IPFS" means**, in plain terms: WebHash Pro pulls your code from GitHub, builds it (if needed) into a folder of static files, and stores that folder on IPFS - a decentralized storage network. You get a permanent content ID (CID) and a public link to your site. There are no servers to manage. {% endhint %} *** ## Before you start A few things to know up front: * **Only static sites and client-side apps work.** WebHash Pro publishes a folder of files (HTML, CSS, JavaScript, images). Anything that needs a running backend or server-side rendering will not work. Plain HTML sites and client-side React/Vite apps are perfect. * **Your first 20 MB of storage is free.** After that, storage is $5/GB, paid in crypto. See the [Billing](https://github.com/WebHash-eth/webhash-pro-app/blob/main/docs/billing.md) guide for details. The deploy screen shows how much storage you have left before you start. * **You deploy from a branch.** WebHash Pro deploys the exact code on the branch you pick, at the moment you click Deploy. *** ## Step 1 - Open the deploy wizard There are two ways to start a deployment: 1. **From the sidebar:** Click **New Deployment**. This opens the deploy wizard with an empty repository picker. 2. **From the Repositories page:** Click **Repositories** in the sidebar, find the repo you want, and click its **Deploy** button. This opens the same wizard with that repository already selected for you. ![New Deployment page with repository and settings cards](/files/hgO4htdlUtDJb1jIuMjX) The wizard has two panels: * **Select Repository** (left) - choose what to deploy and from which branch. * **Deployment Settings** (right) - choose the project type and, if needed, the build command and output folder. At the top you'll also see a **Storage** bar showing how much of your quota is used and how much is free, with a **Buy more storage** link. *** ## Step 2 - Select a GitHub repository In the **Select Repository** panel you'll see a list of your GitHub repositories, most recently updated first. Each repository shows its name, its full `owner/name`, and a colored badge for **public** (green) or **private** (amber). 1. Use the **Search repositories...** box to filter the list by name. 2. Click a repository in the list to select it. The selected repository is highlighted. ### My repository isn't in the list This usually means WebHash Pro doesn't yet have permission to see that repository on GitHub. You have two ways to fix it. #### Option A - Grant access to more repositories (recommended) 1. Click **Add Repository Access** at the top of the page (or **Update GitHub Permissions** if you reached the access prompt while deploying). 2. A dialog explains what will happen. Click **Authorize on GitHub**. 3. GitHub opens and asks which repositories WebHash Pro may access. Select the ones you want (or all of them) and approve. 4. You're returned to the dashboard. Your previously selected repositories stay accessible, and the newly granted ones now appear in the list. ![Grant Additional Repository Access dialog](/files/WU5f6d9PDbIKUfaLj3Nn) #### Option B - Add a repository by URL If a repo still doesn't appear, you can add it manually: 1. Click **Add Repo** next to the search box. 2. Enter the repository in either form: `github.com/owner/repo` or just `owner/repo`. 3. Optionally set the **Default Branch** (usually `main` or `master`). 4. Click **Add Repository**. WebHash Pro checks whether you have access. If you do, the repository is selected and ready to deploy. ![Add Repository Manually dialog](/files/0R5g7FhvfdIuKbVgvhhO) ### When you don't have access at all If the repository is private and you're not a collaborator, you'll see a **Repository Access Required** dialog. It gives you two choices: * **Contact Repository Owner** - clicking **Prepare Email Request** copies the repo URL and opens a pre-filled email asking the owner to either make the repo public or add you as a collaborator. * **Update GitHub Permissions** - re-authorize WebHash Pro on GitHub (the same flow as Option A above), in case it's a repo you actually can access but haven't granted yet. {% hint style="info" %} WebHash Pro only ever sees the repositories you explicitly grant during GitHub sign-in or re-authorization. If you originally chose "only select repositories," use **Add Repository Access** any time to add more. {% endhint %} *** ## Step 3 - Choose a branch Once a repository is selected, a **Branch** dropdown appears. It's pre-filled with the repository's branches, and the first one is selected automatically. 1. Open the **Branch** dropdown. 2. Pick the branch you want to deploy (for example, `main` or `production`). WebHash Pro deploys the code exactly as it is on that branch right now. *** ## Step 4 - Choose the project type In the **Deployment Settings** panel, pick how your project should be built. There are two choices: ### Static Choose **Static** if your repository is already a finished set of files - for example, plain HTML/CSS/JS, or a site you've already built and committed. * No build step runs. * WebHash Pro publishes your repository as-is (from the root folder by default). * The **Build Command** and **Output Directory** fields are disabled - you don't need them. ### React Choose **React** if your repository is a client-side React app (including apps built with Create React App or Vite) that needs to be built before publishing. * Selecting **React** automatically fills in a starting **Build Command** of `npm run build` and an **Output Directory** of `build`. You can change both (see Step 5). * WebHash Pro automatically detects whether your app uses Create React App, Vite, or another setup, and adjusts the build accordingly - so you don't have to specify it. ![Deployment Settings with React project type selected](/files/Ptrht0rE1h72ZfOrP5VR) {% hint style="warning" %} **Only client-side React apps are supported.** If your app relies on a server (server-side rendering, API routes, a database), it won't work on IPFS. The wizard shows this same warning when you pick React. {% endhint %} {% hint style="info" %} **Using Next.js?** Next.js works only if it's configured for a fully static export (`output: 'export'`, which builds to an `out/` folder). Pick **React**, set the **Output Directory** to `out`, and keep your build command. Server/SSR Next.js apps are not supported. {% endhint %} *** ## Step 5 - Set the build command and output directory (React only) For **React** projects, two fields control the build. (For **Static** projects, skip this step - these fields are disabled and ignored.) ### Build Command This is the command WebHash Pro runs to build your app. The default is `npm run build`, which works for most projects. * You can change it to match your project, e.g. `npm run build:prod`. * WebHash Pro picks the right package manager for you based on your lockfile - if your repo has a `yarn.lock` or `pnpm-lock.yaml`, it uses Yarn or pnpm instead of npm automatically. {% hint style="info" %} The build command can't contain shell symbols like `;`, `&`, `|`, `<`, `>`, `$`, backticks, or backslashes. Keep it to a simple command such as `npm run build`. {% endhint %} ### Output Directory This is the folder your build produces - the folder that actually gets published to IPFS. The default is `build`. * **Create React App** builds to `build`. * **Vite** usually builds to `dist`. * **Next.js static export** builds to `out`. If you're not sure, leave the default and check the logs after deploying. If WebHash Pro can't find your specified folder, it automatically looks in the common ones (`dist`, `build`, `out`, `public`) and uses the first it finds. ![Build command and output directory fields filled](/files/Ptrht0rE1h72ZfOrP5VR) *** ## Step 6 - Add environment variables for the build (optional) If your app needs configuration values at build time (for example an API URL or a public key), set them up **before** you deploy, on the dedicated **Environment Variables** page. 1. In the sidebar, click **Environment Variables**. 2. Choose the repository from the **Select Repository** dropdown. Variables are saved **per repository**. 3. Click **Add Variable**, then enter a **Key** and **Value**. 4. Toggle **Secret** on for values you'd rather hide in the interface (they're still used during the build). 5. Click **Save Variables**. Your variables are encrypted at rest and injected into the build the next time you deploy that repository. ![Environment Variables secret row](/files/cPlr9q4L4681kSgyort0) {% hint style="warning" %} **For React apps, variable names must start with `REACT_APP_`** (for example `REACT_APP_API_URL`) to be picked up by the build. For Vite, use the `VITE_` prefix and read them via `import.meta.env`. {% endhint %} {% hint style="warning" %} **Anything in a client-side bundle is public.** Environment variables get baked into the published files, which anyone can read. Only use them for non-sensitive config or public keys - never for passwords or private secrets. {% endhint %} {% hint style="info" %} Saved values are never shown again. When you revisit the page, value fields are blank - leave a field blank to keep the stored value, or type a new value to replace it. Changes take effect on your next deployment. {% endhint %} *** ## Step 7 - Deploy When your repository, branch, project type, and (for React) build settings are ready: 1. Click **Deploy to IPFS** at the bottom of the **Deployment Settings** panel. 2. WebHash Pro first verifies you still have access to the repository, then queues the build. The button changes to **Deploying...** and a **Deployment Progress** section appears with live logs. ![Deploy to IPFS button on Deployment Settings card](/files/Ptrht0rE1h72ZfOrP5VR) {% hint style="info" %} You can only run one deployment at a time from the wizard. Large projects can take several minutes to build and upload. {% endhint %} ### If storage is full If you've used up your storage quota, deploying stops immediately and a red **Storage full** banner appears with a **Go to Billing →** link. Buy more storage (see the [Billing](https://github.com/WebHash-eth/webhash-pro-app/blob/main/docs/billing.md) guide) and try again. Nothing is built or charged when this happens. *** ## Step 8 - Watch the build and live logs After you deploy, the **Deployment Progress** panel streams logs in real time, updating every couple of seconds. Each line is timestamped and color-coded: blue for info, green for success, red for errors. A deployment moves through these statuses: | Status | What it means | | ------------ | ------------------------------------------------------------------------------------------------------------------------ | | **Pending** | The build has been queued and is waiting to start. | | **Building** | WebHash Pro is cloning your repo, installing dependencies, running your build command, and uploading the result to IPFS. | | **Success** | The site is built, uploaded, and live. You'll get a CID and a gateway link. | | **Failed** | Something went wrong. The error is shown in the logs and in a red banner. | While it runs you'll see a spinner labeled **Deployment in progress**. You can leave this page open and watch, or open the full deployment view for the same logs (see Step 9). *** ## Step 9 - Your result: CID, gateway URL, and size When the status reaches **Success**, a green **Deployed successfully** box appears showing: * **Gateway URL** - a clickable public link to your live site. Click it to open your site in a new tab. * **CID** - the IPFS content identifier for this exact version of your site. The CID is permanent and unique to this build; if you deploy again, you get a new CID. * A **View deployment details →** link to the full deployment page. On the **deployment details** page (reached via that link, or via **Deployments** in the sidebar) you'll find the full record: * Repository, branch, project type, and the date deployed. * **Size** of the published site (in MB) - this is what counts against your storage quota. * The **CID** and **Gateway URL**, each with a copy button. * Your build command and output directory. * A **Connect ENS Domain** button to point an ENS name at this deployment (see [Connecting an ENS Domain](https://github.com/WebHash-eth/webhash-pro-app/blob/main/docs/connecting-an-ens-domain.md)). ![Deployment Details page with IPFS information](/files/nlFae4CQ1gGO8FDZWwuL) {% hint style="success" %} That's it - your site is live on IPFS. Share the gateway URL, or connect an ENS domain so people can visit it by name. To make your `main` branch redeploy automatically on every push, see [Auto-Deploy on Push](/auto-deploy.md). {% endhint %} *** ## If a deployment fails When a deployment fails, you'll see a red **Deployment failed** banner with the error message (and an error code, if there is one). The most common causes: * **Build command failed** - a step like `npm run build` errored. Read the red lines in the logs to see exactly what broke (often a missing dependency or a code error). * **Output directory not found** - your build didn't produce the folder you specified. Check the [Output Directory](#step-5--set-the-build-command-and-output-directory-react-only) (e.g. Vite uses `dist`, not `build`). * **Missing environment variable** - the build expected a value you didn't set. Add it on the **Environment Variables** page (Step 6) and deploy again. * **Wrong project type** - a React app deployed as **Static** (or vice versa). Switch the project type and retry. * **No access to the repository** - re-authorize GitHub via **Add Repository Access** (Step 2). * **Timed out** - very large repositories or slow builds can time out after 30 minutes. Reduce the size of what you're deploying if possible. ### How to redeploy WebHash Pro creates a fresh deployment each time, so "redeploying" simply means running the deploy again after fixing the problem: 1. Fix the cause (correct the output directory, add the missing variable, push a code fix to GitHub, etc.). 2. Return to **New Deployment**, select the same repository and branch, confirm your settings, and click **Deploy to IPFS** again. Each attempt is recorded separately, so you can review the logs of past failed and successful builds under **Deployments**. {% hint style="info" %} If you've enabled [Auto-Deploy on Push](/auto-deploy.md) for a repository, pushing a fix to the watched branch will also trigger a new deployment automatically - no need to open the wizard. {% endhint %} --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://prodocs.webhash.com/deploying-a-site.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.