🖥️ Can Hosting on the ICP be Easy as 1-2-3?

Use Our Tool & Deploy in Minutes!

I ran into SOOO many issues while learning to host websites on the ICP, despite being quite experienced in building & hosting traditional websites, so I decided to document everything I encountered and created this site/tool to make things easier for the next person (runs 100% inside your browser--no data collected).

ICP Hosting Flow Chart

The Basic Concept: After your website/page is created and ready, create a new canister on the ICP NNS, create necessary files and proper project folders, then in your computer's Bash terminal (standard on MAC, installable on Windows) download and install DFX from Dfinity which is the tool for uploading your local web files to your canister on the ICP. Finally, you would setup your custom domain name to connect to the canister with advanced DNS settings. There will be a lot of little details involved, and I will cover everything step by step!

📂 First, Get Your Website Files Ready

Create your website/page with HTML, your favorite WYSIWYG editor, or even with ChatGPT! Just make sure to have your web files tested locally and ready to go (html, image files, css, js, etc.). Make sure it is static, which means it doesn't require server-side backends/databases. Try my FAST AI website generator to create a simple multi-page website on any topic if you like!

♾️ Create a New Canister in Your ICP NNS

Navigate to https://nns.ic0.app and sign in with your Internet Identity (or create one now). Click the profile icon (top right). Go to "Canisters", create and fund one with the required 2T cycles (barely a few dollars in ICP), then copy the canister name & ID for the next step.

1. Create JSON Files (Part of Download in Step 3)

To begin, we will need some files to be created and configured with your canister related info which will need to be placed in the appropriate folder structures. I will help you set those up here.

2. Create Domain Related Files (Part of Download in Step 3)

Now we need some domain related files to be created and configured. They will also be placed in the appropriate folder structures.

If you don't have a domain yet we can use mydomain.com as a placeholder, but be sure edit the ic-domains file later with your actual domains (or run this tool again).

3. Download Project Files & Folders

Ready to Download!

You're about to download a complete project package pre-configured for Internet Computer deployment. This zip file will contain:

  • An empty "assets" folder under your project root folder--this is where you will put all your website files
  • Automatically populated canister_ids.json, dfx.json and .ic-assets.json files in the project root folder
  • A filed called ic-domains that sits inside a newly created folder ".well-known" which sits inside the "assets" folder

When you click "Download", you'll receive a zip file containing all the files we just created in all the proper folder structures. Just extract and drop all the files into your project folder on your computer.

Next, drop all your website related files (index.html, etc.) into the "assets" folder.

Here's an example of what the directory structure may look like inside your project folder:

├── .ic-assets.json
├── assets
│   ├── .well-known
│   │   └── ic-domains
│   ├── app.js
│   ├── styles.css
│   ├── image.png
│   └── index.html
├── canister_ids.json
└── dfx.json

4. Set Up Terminal Access

Now that you've downloaded the project structure, follow these steps to run terminal on your computer:

Open Terminal on your local computer
Mac Users:

Open Terminal by:

  • Pressing Command + Space to open Spotlight
  • Typing "Terminal"
  • Pressing Enter

Navigate to your project folder:

cd /users/username/desktop/project_folder
Windows Users:

Since Windows do not come preinstalled with native Bash (Bourne Again SHell), we now need to install Windows Subsystem for Linux (WSL) in order to have Bash for upcoming steps. Use the following command in terminal/PowerShell to install WSL:

wsl --install

After installation is complete you'll be asked to reboot your computer. After rebooting, open terminal/PowerShell again and run wsl --install again and it will download and install the WSL instance Ubuntu. When this finishes you are ready to run WSL for the first time:

wsl

You will now be asked to create a new Unix user account and a password. After doing so, the installation is complete, you are in the WSL/Bash environment! Now navigate to your project directory using the commands below:

cd /mnt/c/users/YOURUSERNAME/PROJECTFOLDERNAME (or wherever your project folder is located)
Common Directory Navigation Commands
  • pwd Print current directory path
  • ls List files and directories in current location
  • cd .. Move up one directory level
  • cd / Move to root directory
  • cd ~ Move to home directory
  • cd foldername Move into a specific folder

5. Setting Up DFX and Deploying to ICP

  1. Install DFX (Dfinity Command-Line Execution Environment)

    *** You only have to install DFX once. For subsequent deloyments you just need to make sure you are in your Bash terminal environment, where you'd start DFX and then use DFX to deploy your site. See commands in step 6 of this section.

    sh -ci "$(curl -fsSL https://internetcomputer.org/install.sh)"

    Be sure to exit out of the current terminal (type 'exit') and restart it again so that DFX will take effect (open powershell and run wsl again). Now we can check if DFX is working with the following command:

  2. Get Principal ID of DFX and add as Controller in NNS 
    dfx identity get-principal
    Principal ID Explanation:

    When you run this command, DFX will create default as the user name of the identity. At the end of the output, you'll see a long identity string separated by dashes. This is your Principal ID for the default user. Make sure to copy this entire Principal ID for the next step.

    Example output might look like: abc123-def456-ghi789-xyz...

  3. Important Next Step:

    After obtaining your Principal ID, go back to the Internet Computer Network Nervous System (NNS) website:

    1. Navigate to https://nns.ic0.app
    2. Click on the profile icon in the upper right corner
    3. Go to "Canisters"
    4. Find the canister you're working with
    5. Add this Principal ID as a Controller to the canister

    This step is crucial to allow your local DFX to have access and deploy to the canister.

  4. Deploy Your Website Contents to ICP

    This command starts the DFX server in the background, creating a local environment needed for deployment. It ensures the server is running and ready for subsequent deployment steps.

    dfx start --clean --background

    Now that DFX is running, the next line of code will deploy your local web files in the "assets" folder to your Internet Computer Canister.

    dfx deploy --network ic --no-wallet
    5. Grant Permissions to Your Canister (if deployment unsuccessful)

    *** If you didn't get the canister URL toward the end of the long deployment resonse and encountered permission related errors, you likely need to grant specific permissions to that principal ID.

    This usually only happens to additional canister controller IDs being used to deploy your site when you are using another device/computer to deploy to a canister which has different principal IDs. Use the tool below to generate the commands needed:

    Grant COMMIT Permission

    dfx canister call --network ic <your_canister_id> grant_permission '(record {permission = variant {Commit}; to_principal = principal "<your_principal_id>"})'

    Grant PREPARE Permission

    dfx canister call --network ic <your_canister_id> grant_permission '(record {permission = variant {Prepare}; to_principal = principal "<your_principal_id>"})'
    Important Instructions:
    1. Copy and paste the Commit Permission Command into your terminal (Bash).
    2. Wait for the response. Look for () at the end, which means permission was successfully granted.
    3. Then copy and paste the Grant PREPARE Permission into your terminal (Bash).
    4. Again, look for () at the end to confirm successful permission grant.
  5. Update Your Website

    When you want to make changes to your website:

    1. Update your website files in the "assets" folder locally
    2. Open your terminal, run Bash in PowerShell (wsl)
    3. Repeat The Above Step: 5. Deploy Your Website Contents to ICP
  6. Additional DFX Commands

    Helpful commands for managing your DFX identities:

    • dfx identity list - Shows list of IDs
    • dfx identity new <user_name> - Adds a new identity name (will ask you to setup password)
    • dfx identity use <user_name> - Select the specific user name to be used instead of default
    • dfx identity get-principal - Shows current user name/identify's principal ID

6. Use Custom Domains for Your ICP Site

Want to use your own custom domain with your Internet Computer hosted website?

Domain Setup Prerequisites:

If you completed the domain configuration earlier in this process and downloaded the project structure, you're already partway there!

DNS Configuration Steps

  1. Access Domain Registrar Settings

    Log into your domain registrar's control panel (e.g., GoDaddy, Namecheap, Google Domains).

  2. Add DNS Records

    In the advanced or custom DNS settings, add these three records:

    Type Host Value TTL
    ALIAS Record @ mydomain.com.icp1.io Automatic
    CNAME Record _acme-challenge _acme-challenge.mydomain.com.icp2.io Automatic
    TXT Record _canister-id my-icp-canister-id-cai Automatic
  3. Register Domain on Internet Computer

    After configuring DNS records, run the following command in your terminal:

    curl -sL -X POST -H 'Content-Type: application/json' https://icp0.io/registrations --data '{"name": "mydomain.com"}'
    Note: Your website should be deloyed/uploaded on the Internet Computer now! It should work immediately via the url given in he terminal response after deployment command. If you have completed the domain setup on the IC and DNS settings on your domain registrar, then you should be able to see your website by navigating to your custom domain as well!