From 224e896cf15aeb336476abcb749e21227acdd924 Mon Sep 17 00:00:00 2001 From: David Dal Busco Date: Tue, 19 Nov 2024 09:58:21 +0100 Subject: [PATCH 1/8] docs: configuration Signed-off-by: David Dal Busco --- docs/build/components/assertions.mdx | 33 ++ docs/build/components/encoding.mdx | 27 ++ docs/build/components/gzip.mdx | 31 ++ docs/build/components/http-headers.mdx | 47 +++ docs/build/components/iframe.mdx | 17 + docs/build/components/ignore-files.mdx | 17 + docs/build/components/redirects.mdx | 31 ++ docs/build/components/rewrites.mdx | 31 ++ docs/build/components/source.mdx | 3 + docs/build/hosting.md | 382 ------------------ docs/build/hosting.mdx | 172 ++++++++ docs/build/storage.md | 2 +- docs/intro.md | 2 +- .../{configuration.md => configuration.mdx} | 81 +++- docs/setup-the-sdk.md | 2 +- docs/troubleshooting.md | 2 +- docusaurus.config.ts | 6 +- something.config.ts | 10 + 18 files changed, 506 insertions(+), 390 deletions(-) create mode 100644 docs/build/components/assertions.mdx create mode 100644 docs/build/components/encoding.mdx create mode 100644 docs/build/components/gzip.mdx create mode 100644 docs/build/components/http-headers.mdx create mode 100644 docs/build/components/iframe.mdx create mode 100644 docs/build/components/ignore-files.mdx create mode 100644 docs/build/components/redirects.mdx create mode 100644 docs/build/components/rewrites.mdx create mode 100644 docs/build/components/source.mdx delete mode 100644 docs/build/hosting.md create mode 100644 docs/build/hosting.mdx rename docs/miscellaneous/{configuration.md => configuration.mdx} (60%) create mode 100644 something.config.ts diff --git a/docs/build/components/assertions.mdx b/docs/build/components/assertions.mdx new file mode 100644 index 00000000..c8a14d1e --- /dev/null +++ b/docs/build/components/assertions.mdx @@ -0,0 +1,33 @@ +The CLI conducts several assertions when interacting with your Satellite, one of which involves monitoring the heap memory size. Typically, the CLI checks to ensure that the heap memory does not exceed the 1 GB limit before deployment. For instance, if your heap memory usage is close to 900 MB, the CLI will prompt you to confirm the deployment. + +You can customize this behavior by adjusting the heap memory limit in bytes. For example, to set a new limit of 678 MB, update your configuration as follows: + +```javascript +import { defineConfig } from "@junobuild/config"; + +export default defineConfig({ + satellite: { + id: "qsgjb-riaaa-aaaaa-aaaga-cai", + source: "dist", + assertions: { + heapMemory: 678000000 + } + } +}); +``` + +Alternatively, these checks can be completely disabled. To do so, set the `heapMemory` assertion to `false`: + +```javascript +import { defineConfig } from "@junobuild/config"; + +export default defineConfig({ + satellite: { + id: "qsgjb-riaaa-aaaaa-aaaga-cai", + source: "dist", + assertions: { + heapMemory: false + } + } +}); +``` diff --git a/docs/build/components/encoding.mdx b/docs/build/components/encoding.mdx new file mode 100644 index 00000000..663c841c --- /dev/null +++ b/docs/build/components/encoding.mdx @@ -0,0 +1,27 @@ +When deploying, the CLI automatically maps the encoding type based on the file extension. The encoding information is then used in the satellite to provide the appropriate HTTP response header `Content-Encoding`. + +The default mappings are as follows: + +- `.Z` = `compress` +- `.gz` = `gzip` +- `.br` = `br` +- `.zlib` = `deflate` +- rest = `identity` (no compression) + +You can also customize the encoding behavior by using the "encoding" attribute in the configuration file. + +This attribute works similarly to Git's `.gitignore`, and you can specify which files to ignore using globs. + +Here is an example of how the "encoding" attribute can be utilized: + +```javascript +import { defineConfig } from "@junobuild/config"; + +export default defineConfig({ + satellite: { + id: "qsgjb-riaaa-aaaaa-aaaga-cai", + source: "dist", + encoding: [["**/releases/*.gz", "identity"]] + } +}); +``` diff --git a/docs/build/components/gzip.mdx b/docs/build/components/gzip.mdx new file mode 100644 index 00000000..e6aaffc1 --- /dev/null +++ b/docs/build/components/gzip.mdx @@ -0,0 +1,31 @@ +When deploying your application, the CLI automatically searches for JavaScript (js), ES Module (mjs), and CSS (css) files in the `source` folder and optimizes them using Gzip compression. This is useful because neither the protocol nor a satellite can compress these files, ensuring the best web performance. + +If you wish to customize this behavior, you have the option to disable it or provide a different file matching pattern using glob syntax. + +To opt-out of Gzip compression, simply set the `gzip` option to `false` in your configuration: + +```javascript +import { defineConfig } from "@junobuild/config"; + +export default defineConfig({ + satellite: { + id: "qsgjb-riaaa-aaaaa-aaaga-cai", + source: "dist", + gzip: false + } +}); +``` + +If you want to customize the default pattern `**/*.+(css|js|mjs)` to better suit your needs, you can specify your own pattern. For example: + +```javascript +import { defineConfig } from "@junobuild/config"; + +export default defineConfig({ + satellite: { + id: "qsgjb-riaaa-aaaaa-aaaga-cai", + source: "dist", + gzip: "**/*.jpg" + } +}); +``` diff --git a/docs/build/components/http-headers.mdx b/docs/build/components/http-headers.mdx new file mode 100644 index 00000000..78ae3084 --- /dev/null +++ b/docs/build/components/http-headers.mdx @@ -0,0 +1,47 @@ +Headers allow the client and the satellite to pass additional information along with a request or a response. Some sets of headers can affect how the browser handles the page and its content. + +For instance, you may want to set a specific `Cache-Control` for performance reasons. + +Here's an example of the `headers` object: + +```javascript +import { defineConfig } from "@junobuild/config"; + +export default defineConfig({ + satellite: { + id: "qsgjb-riaaa-aaaaa-aaaga-cai", + source: "dist", + storage: { + headers: [ + { + source: "/", + headers: [["Cache-Control", "public,max-age=0,must-revalidate"]] + }, + { + source: "assets/fonts/*", + headers: [["Cache-Control", "max-age=31536000"]] + }, + { + source: "**/*.jpg", + headers: [ + ["Cache-Control", "max-age=31536000"], + ["Access-Control-Allow-Origin", "*"] + ] + } + ] + } + } +}); +``` + +This `source` attribute works similarly to Git's `.gitignore`, and you can specify which files match the headers using globs. + +The `headers` is an array of objects, each containing `key` and `value`, and these apply to the matching paths. + +:::note + +- The `Content-Type` header is calculated automatically and cannot be altered. +- No validation or check for uniqueness is performed. For example, if a header matches a file based on multiple rules, multiple headers will be set. +- Likewise, if you provide the same header when you [upload](https://juno.build/docs/build/storage#upload-asset) file to your "Storage" and within the configuration, both headers will be set in the response. + +::: diff --git a/docs/build/components/iframe.mdx b/docs/build/components/iframe.mdx new file mode 100644 index 00000000..1d735cf4 --- /dev/null +++ b/docs/build/components/iframe.mdx @@ -0,0 +1,17 @@ +For security reasons and to prevent click-jacking attacks, dapps deployed with Juno are, by default, set to deny embedding in other sites. + +You can customize this behavior by setting the `iframe` option to either `same-origin`, which restricts your pages to be displayed only if all ancestor frames have the same origin as the page itself, or `allow-any`, which allows your project to be embeddable by any site. + +```javascript +import { defineConfig } from "@junobuild/config"; + +export default defineConfig({ + satellite: { + id: "qsgjb-riaaa-aaaaa-aaaga-cai", + source: "dist", + storage: { + iframe: "same-origin" + } + } +}); +``` diff --git a/docs/build/components/ignore-files.mdx b/docs/build/components/ignore-files.mdx new file mode 100644 index 00000000..2fdb23a0 --- /dev/null +++ b/docs/build/components/ignore-files.mdx @@ -0,0 +1,17 @@ +The `ignore` attribute allows you to exclude certain files from being deployed to your satellite. + +This attribute works similarly to Git's `.gitignore`, and you can specify which files to ignore using globs. + +Here is an example of how the ignore attribute can be utilized: + +```javascript +import { defineConfig } from "@junobuild/config"; + +export default defineConfig({ + satellite: { + id: "qsgjb-riaaa-aaaaa-aaaga-cai", + source: "dist", + ignore: ["**/*.txt", ".tmp/"] + } +}); +``` diff --git a/docs/build/components/redirects.mdx b/docs/build/components/redirects.mdx new file mode 100644 index 00000000..7bb31354 --- /dev/null +++ b/docs/build/components/redirects.mdx @@ -0,0 +1,31 @@ +Use a URL redirect to prevent broken links if you've moved a page or to shorten URLs. For example, you could redirect a browser from `juno.build/start-building` to `juno.build/get-started.html`. + +Here's the basic structure for a `redirects` attribute. + +```javascript +import { defineConfig } from "@junobuild/config"; + +export default defineConfig({ + satellite: { + id: "qsgjb-riaaa-aaaaa-aaaga-cai", + source: "dist", + storage: { + redirects: [ + { + source: "/hello", + location: "/world/index.html", + code: 300 + } + ] + } + } +}); +``` + +The `redirects` attribute contains an array of redirect rules: + +| Field | Description | +| ------------ | ------------------------------------------------------------------------------------------------------------------------------- | +| **source** | This `source` attribute works similarly to Git's `.gitignore`, and you can specify which files match the redirects using globs. | +| **location** | A relative path to where the browser should make a new request. | +| **code** | The HTTPS response code. Use a type of `301` for 'Moved Permanently' or `302` for 'Found' (Temporary Redirect). | diff --git a/docs/build/components/rewrites.mdx b/docs/build/components/rewrites.mdx new file mode 100644 index 00000000..74c0d21d --- /dev/null +++ b/docs/build/components/rewrites.mdx @@ -0,0 +1,31 @@ +You can utilize optional rewrites to display the same content for multiple URLs. Rewrites are especially useful when combined with pattern matching, allowing acceptance of any URL that matches the pattern. + +Here's the basic structure for a `rewrites` attribute. + +```javascript +import { defineConfig } from "@junobuild/config"; + +export default defineConfig({ + satellite: { + id: "qsgjb-riaaa-aaaaa-aaaga-cai", + source: "dist", + storage: { + rewrites: [ + { + source: "/hello/**", + destination: "/hello/world.html" + } + ] + } + } +}); +``` + +This `source` attribute works similarly to Git's `.gitignore`, and you can specify which files match the rewrites using globs. + +:::note + +- Rewrites are only applied to requests that do not match any existing resources. +- By default, all unknown paths are automatically rewritten to `/index.html` (or `/404.html` if you provide such a page). You cannot disable this default behavior. + +::: diff --git a/docs/build/components/source.mdx b/docs/build/components/source.mdx new file mode 100644 index 00000000..af04f427 --- /dev/null +++ b/docs/build/components/source.mdx @@ -0,0 +1,3 @@ +Where should Juno search for the files to deploy in your project directory. + +This is commonly the output folder of `npm run build`, such as `/dist` or `/build`. diff --git a/docs/build/hosting.md b/docs/build/hosting.md deleted file mode 100644 index a158eeb6..00000000 --- a/docs/build/hosting.md +++ /dev/null @@ -1,382 +0,0 @@ ---- -sidebar_position: 4 -description: "Discover Juno Hosting: Fast, Secure, Blockchain-Powered Web Hosting. Deploy with ease and custom domains." -keywords: [Fast hosting, Secure hosting, Blockchain hosting, Custom domains] ---- - -# Hosting - -Juno Hosting offers fast and secure hosting powered by 100% blockchain technology. - -With just one [CLI] command, you can effortlessly deploy your web applications, static, and dynamic content to your [satellite]. - ---- - -## Custom Domain Support - -You can maintain your unique brand identity with Juno Hosting. Use your custom domain, such as "yolo.com" or "hello.world.com", instead of the default domain name provided by Juno. - -Our infrastructure automatically provisions an SSL certificate for each of your domains, ensuring secure connections for your users. - -### Connecting Your Domain - -To connect your custom domain, follow these steps: - -1. Start the custom domain wizard from the Juno console [hosting](https://console.juno.build/hosting) page -2. Enter the desired domain name for your satellite -3. Log into your domain provider's site and configure the DNS records as indicated by Juno -4. Continue the process in Juno - -Please note that it may take several minutes to set up your custom domain after the wizard is completed and up to 24 hours for your domain provider to reflect the changes. - -### About DNS records - -To configure DNS records, you will be requested to use `CNAME` records. Some domain providers do not provide such types. Instead, DNS providers often support so-called `CNAME` flattening. To this end, these DNS providers offer flattened record types, such as `ANAME` or `ALIAS` records, which can be used instead of the `CNAME` to `icp1.io`. - -Some DNS providers require you to specify the main domain. For example, you might have to specify your full domain `foo.bar.com` for the `CNAME` entry related to `icp1.io` instead of only `foo` as displayed by our [console]. - -If you ever encounter issues configuring your DNS, you can also refer to the [Troubleshooting](https://internetcomputer.org/docs/current/developer-docs/production/custom-domain/#troubleshooting) section for further assistance. - -### Cloudflare - -The DNS entries presented in the console are exactly the ones that should be configured in Cloudflare. - -However, based on our experience, to enable the custom domain properly, the following settings in Cloudflare should be disabled: - -- DNS > Settings > Disable DNSSEC -- SSL/TLS > Overview > Set "Your SSL/TLS encryption mode" to "Off (not secure)". A SSL certificate will be automatically ordered by configuring the custom domain. -- SSL/TLS > Edge Certificates > Disable Universal SSL - -Additionally, we recommend not proxying the DNS entries ("DNS only"). - -### Namecheap - -This external guide provides instructions on how to configure the DNS records for [Namecheap](https://internetcomputer.org/docs/current/developer-docs/production/custom-domain/dns-setup#namecheap). - -### GoDaddy - -This external guide provides instructions on how to configure the DNS records for [GoDaddy](https://internetcomputer.org/docs/current/developer-docs/production/custom-domain/dns-setup#godaddy). - -### Google Domains - -Google Domains does not support `CNAME` records for the apex domain. For this reason, we suggest transferring the domain to [Cloudflare](#cloudflare). - -### Other Limited Providers - -We are aware of a few other providers that also do not support `CNAME` records for the apex domain. Similar to Google Domains, we advise transferring the domain to [Cloudflare](#cloudflare) in order to overcome this limitation. - -- HostGator -- Infomaniak - -### Status - -The status of the configuration of your custom domain can be one of the following: - -- `PendingOrder`: The registration request has been submitted and is waiting to be picked up. -- `PendingChallengeResponse`: The certificate has been ordered. -- `PendingAcmeApproval`: The challenge has been completed. -- `Available`: The registration request has been successfully processed. Your custom domain is ready. -- `Failed`: The registration request failed. - -If one of the status `Pending...` is reached, the console will automatically refresh the status every few seconds until your domain is available. - ---- - -## Configure Hosting behavior - -You can configure customized hosting behavior for requests to your site. - -#### What can you configure? - -- Specify which `source` files in your local project directory you want to deploy? [Learn how.](#source) -- Ignore some files during deployment. [Learn how.](#ignore-files) -- Configure HTTP `headers` to pass along additional information about a request or a response. [Learn how.](#http-headers) -- Serve a customized 404 page. [Learn how.](#customize-a-404not-found-page) -- Set up `redirects` for pages that you've moved or deleted. [Learn how.](#redirects) -- Set up `rewrites`. [Learn how.](#rewrites) -- Tweak `gzip` compression for best performance. [Learn how.](#gzip) -- Customize the `encoding` behavior of your files. [Learn how.](#encoding-types) -- Allow your project to be embedded as an `iframe`. [Learn how.](#iframe) -- Customize `assertions` to modify the default verification behavior of the CLI. [Learn how.](#assertions) - -#### Where do you define your Hosting configuration? - -You define your Hosting configuration in your Juno configuration file. The CLI automatically creates the file at the root of your project directory when you run the [juno init](../miscellaneous/cli.mdx#init) or [juno deploy](../miscellaneous/cli.mdx#deploy) command for the first time. - -#### How do you apply your changes? - -To apply any changes you make in your configuration to your satellite, execute the [juno config](../miscellaneous/cli.mdx#config) command with the CLI. - -### Source - -Where should Juno search for the files to deploy in your project directory. - -This is commonly the output folder of `npm run build`, such as `/dist` or `/build`. - -### Ignore files - -The `ignore` attribute allows you to exclude certain files from being deployed to your satellite. - -This attribute works similarly to Git's `.gitignore`, and you can specify which files to ignore using globs. - -Here is an example of how the ignore attribute can be utilized: - -```javascript -import { defineConfig } from "@junobuild/config"; - -export default defineConfig({ - satellite: { - id: "qsgjb-riaaa-aaaaa-aaaga-cai", - source: "dist", - ignore: ["**/*.txt", ".tmp/"] - } -}); -``` - -### HTTP Headers - -Headers allow the client and the satellite to pass additional information along with a request or a response. Some sets of headers can affect how the browser handles the page and its content. - -For instance, you may want to set a specific `Cache-Control` for performance reasons. - -Here's an example of the `headers` object: - -```javascript -import { defineConfig } from "@junobuild/config"; - -export default defineConfig({ - satellite: { - id: "qsgjb-riaaa-aaaaa-aaaga-cai", - source: "dist", - storage: { - headers: [ - { - source: "/", - headers: [["Cache-Control", "public,max-age=0,must-revalidate"]] - }, - { - source: "assets/fonts/*", - headers: [["Cache-Control", "max-age=31536000"]] - }, - { - source: "**/*.jpg", - headers: [ - ["Cache-Control", "max-age=31536000"], - ["Access-Control-Allow-Origin", "*"] - ] - } - ] - } - } -}); -``` - -This `source` attribute works similarly to Git's `.gitignore`, and you can specify which files match the headers using globs. - -The `headers` is an array of objects, each containing `key` and `value`, and these apply to the matching paths. - -:::note - -- The `Content-Type` header is calculated automatically and cannot be altered. -- No validation or check for uniqueness is performed. For example, if a header matches a file based on multiple rules, multiple headers will be set. -- Likewise, if you provide the same header when you [upload](https://juno.build/docs/build/storage#upload-asset) file to your "Storage" and within the configuration, both headers will be set in the response. - -::: - -### Customize a 404/Not Found page - -By default, all unknown paths are automatically rewritten to `/index.html`. However, if you wish to serve a custom `404 Not Found` error when a user attempts to access a non-existent page, you can do so without requiring additional configuration. - -Simply upload a custom `404.html` file to your satellite that should be served from the root path of your site. - -### Redirects - -Use a URL redirect to prevent broken links if you've moved a page or to shorten URLs. For example, you could redirect a browser from `juno.build/start-building` to `juno.build/get-started.html`. - -Here's the basic structure for a `redirects` attribute. - -```javascript -import { defineConfig } from "@junobuild/config"; - -export default defineConfig({ - satellite: { - id: "qsgjb-riaaa-aaaaa-aaaga-cai", - source: "dist", - storage: { - redirects: [ - { - source: "/hello", - location: "/world/index.html", - code: 300 - } - ] - } - } -}); -``` - -The `redirects` attribute contains an array of redirect rules: - -| Field | Description | -| ------------ | ------------------------------------------------------------------------------------------------------------------------------- | -| **source** | This `source` attribute works similarly to Git's `.gitignore`, and you can specify which files match the redirects using globs. | -| **location** | A relative path to where the browser should make a new request. | -| **code** | The HTTPS response code. Use a type of `301` for 'Moved Permanently' or `302` for 'Found' (Temporary Redirect). | - -### Rewrites - -You can utilize optional rewrites to display the same content for multiple URLs. Rewrites are especially useful when combined with pattern matching, allowing acceptance of any URL that matches the pattern. - -Here's the basic structure for a `rewrites` attribute. - -```javascript -import { defineConfig } from "@junobuild/config"; - -export default defineConfig({ - satellite: { - id: "qsgjb-riaaa-aaaaa-aaaga-cai", - source: "dist", - storage: { - rewrites: [ - { - source: "/hello/**", - destination: "/hello/world.html" - } - ] - } - } -}); -``` - -This `source` attribute works similarly to Git's `.gitignore`, and you can specify which files match the rewrites using globs. - -:::note - -- Rewrites are only applied to requests that do not match any existing resources. -- By default, all unknown paths are automatically rewritten to `/index.html` (or `/404.html` if you provide such a page). You cannot disable this default behavior. - -::: - -### GZIP - -When deploying your application, the CLI automatically searches for JavaScript (js), ES Module (mjs), and CSS (css) files in the `source` folder and optimizes them using Gzip compression. This is useful because neither the protocol nor a satellite can compress these files, ensuring the best web performance. - -If you wish to customize this behavior, you have the option to disable it or provide a different file matching pattern using glob syntax. - -To opt-out of Gzip compression, simply set the `gzip` option to `false` in your configuration: - -```javascript -import { defineConfig } from "@junobuild/config"; - -export default defineConfig({ - satellite: { - id: "qsgjb-riaaa-aaaaa-aaaga-cai", - source: "dist", - gzip: false - } -}); -``` - -If you want to customize the default pattern `**/*.+(css|js|mjs)` to better suit your needs, you can specify your own pattern. For example: - -```javascript -import { defineConfig } from "@junobuild/config"; - -export default defineConfig({ - satellite: { - id: "qsgjb-riaaa-aaaaa-aaaga-cai", - source: "dist", - gzip: "**/*.jpg" - } -}); -``` - -### Encoding types - -When deploying, the CLI automatically maps the encoding type based on the file extension. The encoding information is then used in the satellite to provide the appropriate HTTP response header `Content-Encoding`. - -The default mappings are as follows: - -- `.Z` = `compress` -- `.gz` = `gzip` -- `.br` = `br` -- `.zlib` = `deflate` -- rest = `identity` (no compression) - -You can also customize the encoding behavior by using the "encoding" attribute in the configuration file. - -This attribute works similarly to Git's `.gitignore`, and you can specify which files to ignore using globs. - -Here is an example of how the "encoding" attribute can be utilized: - -```javascript -import { defineConfig } from "@junobuild/config"; - -export default defineConfig({ - satellite: { - id: "qsgjb-riaaa-aaaaa-aaaga-cai", - source: "dist", - encoding: [["**/releases/*.gz", "identity"]] - } -}); -``` - -### iframe - -For security reasons and to prevent click-jacking attacks, dapps deployed with Juno are, by default, set to deny embedding in other sites. - -You can customize this behavior by setting the `iframe` option to either `same-origin`, which restricts your pages to be displayed only if all ancestor frames have the same origin as the page itself, or `allow-any`, which allows your project to be embeddable by any site. - -```javascript -import { defineConfig } from "@junobuild/config"; - -export default defineConfig({ - satellite: { - id: "qsgjb-riaaa-aaaaa-aaaga-cai", - source: "dist", - storage: { - iframe: "same-origin" - } - } -}); -``` - -### Assertions - -The CLI conducts several assertions when interacting with your Satellite, one of which involves monitoring the heap memory size. Typically, the CLI checks to ensure that the heap memory does not exceed the 1 GB limit before deployment. For instance, if your heap memory usage is close to 900 MB, the CLI will prompt you to confirm the deployment. - -You can customize this behavior by adjusting the heap memory limit in bytes. For example, to set a new limit of 678 MB, update your configuration as follows: - -```javascript -import { defineConfig } from "@junobuild/config"; - -export default defineConfig({ - satellite: { - id: "qsgjb-riaaa-aaaaa-aaaga-cai", - source: "dist", - assertions: { - heapMemory: 678000000 - } - } -}); -``` - -Alternatively, these checks can be completely disabled. To do so, set the `heapMemory` assertion to `false`: - -```javascript -import { defineConfig } from "@junobuild/config"; - -export default defineConfig({ - satellite: { - id: "qsgjb-riaaa-aaaaa-aaaga-cai", - source: "dist", - assertions: { - heapMemory: false - } - } -}); -``` - -[CLI]: ../miscellaneous/cli.mdx -[satellite]: ../terminology.md#satellite -[console]: ../terminology.md#console diff --git a/docs/build/hosting.mdx b/docs/build/hosting.mdx new file mode 100644 index 00000000..97f5308d --- /dev/null +++ b/docs/build/hosting.mdx @@ -0,0 +1,172 @@ +--- +sidebar_position: 4 +description: "Discover Juno Hosting: Fast, Secure, Blockchain-Powered Web Hosting. Deploy with ease and custom domains." +keywords: [Fast hosting, Secure hosting, Blockchain hosting, Custom domains] +--- + +# Hosting + +Juno Hosting offers fast and secure hosting powered by 100% blockchain technology. + +With just one [CLI] command, you can effortlessly deploy your web applications, static, and dynamic content to your [satellite]. + +--- + +## Custom Domain Support + +You can maintain your unique brand identity with Juno Hosting. Use your custom domain, such as "yolo.com" or "hello.world.com", instead of the default domain name provided by Juno. + +Our infrastructure automatically provisions an SSL certificate for each of your domains, ensuring secure connections for your users. + +### Connecting Your Domain + +To connect your custom domain, follow these steps: + +1. Start the custom domain wizard from the Juno console [hosting](https://console.juno.build/hosting) page +2. Enter the desired domain name for your satellite +3. Log into your domain provider's site and configure the DNS records as indicated by Juno +4. Continue the process in Juno + +Please note that it may take several minutes to set up your custom domain after the wizard is completed and up to 24 hours for your domain provider to reflect the changes. + +### About DNS records + +To configure DNS records, you will be requested to use `CNAME` records. Some domain providers do not provide such types. Instead, DNS providers often support so-called `CNAME` flattening. To this end, these DNS providers offer flattened record types, such as `ANAME` or `ALIAS` records, which can be used instead of the `CNAME` to `icp1.io`. + +Some DNS providers require you to specify the main domain. For example, you might have to specify your full domain `foo.bar.com` for the `CNAME` entry related to `icp1.io` instead of only `foo` as displayed by our [console]. + +If you ever encounter issues configuring your DNS, you can also refer to the [Troubleshooting](https://internetcomputer.org/docs/current/developer-docs/production/custom-domain/#troubleshooting) section for further assistance. + +### Cloudflare + +The DNS entries presented in the console are exactly the ones that should be configured in Cloudflare. + +However, based on our experience, to enable the custom domain properly, the following settings in Cloudflare should be disabled: + +- DNS > Settings > Disable DNSSEC +- SSL/TLS > Overview > Set "Your SSL/TLS encryption mode" to "Off (not secure)". A SSL certificate will be automatically ordered by configuring the custom domain. +- SSL/TLS > Edge Certificates > Disable Universal SSL + +Additionally, we recommend not proxying the DNS entries ("DNS only"). + +### Namecheap + +This external guide provides instructions on how to configure the DNS records for [Namecheap](https://internetcomputer.org/docs/current/developer-docs/production/custom-domain/dns-setup#namecheap). + +### GoDaddy + +This external guide provides instructions on how to configure the DNS records for [GoDaddy](https://internetcomputer.org/docs/current/developer-docs/production/custom-domain/dns-setup#godaddy). + +### Google Domains + +Google Domains does not support `CNAME` records for the apex domain. For this reason, we suggest transferring the domain to [Cloudflare](#cloudflare). + +### Other Limited Providers + +We are aware of a few other providers that also do not support `CNAME` records for the apex domain. Similar to Google Domains, we advise transferring the domain to [Cloudflare](#cloudflare) in order to overcome this limitation. + +- HostGator +- Infomaniak + +### Status + +The status of the configuration of your custom domain can be one of the following: + +- `PendingOrder`: The registration request has been submitted and is waiting to be picked up. +- `PendingChallengeResponse`: The certificate has been ordered. +- `PendingAcmeApproval`: The challenge has been completed. +- `Available`: The registration request has been successfully processed. Your custom domain is ready. +- `Failed`: The registration request failed. + +If one of the status `Pending...` is reached, the console will automatically refresh the status every few seconds until your domain is available. + +--- + +## Configure Hosting behavior + +You can configure customized hosting behavior for requests to your site. + +#### What can you configure? + +- Specify which `source` files in your local project directory you want to deploy? [Learn how.](#source) +- Ignore some files during deployment. [Learn how.](#ignore-files) +- Configure HTTP `headers` to pass along additional information about a request or a response. [Learn how.](#http-headers) +- Serve a customized 404 page. [Learn how.](#customize-a-404not-found-page) +- Set up `redirects` for pages that you've moved or deleted. [Learn how.](#redirects) +- Set up `rewrites`. [Learn how.](#rewrites) +- Tweak `gzip` compression for best performance. [Learn how.](#gzip) +- Customize the `encoding` behavior of your files. [Learn how.](#encoding-types) +- Allow your project to be embedded as an `iframe`. [Learn how.](#iframe) +- Customize `assertions` to modify the default verification behavior of the CLI. [Learn how.](#assertions) + +#### Where do you define your Hosting configuration? + +You define your Hosting configuration in your Juno configuration file. The CLI automatically creates the file at the root of your project directory when you run the [juno init](../miscellaneous/cli.mdx#init) or [juno deploy](../miscellaneous/cli.mdx#deploy) command for the first time. + +#### How do you apply your changes? + +To apply any changes you make in your configuration to your satellite, execute the [juno config](../miscellaneous/cli.mdx#config) command with the CLI. + +### Source + +import Source from "./components/source.mdx"; + + + +### Ignore files + +import IgnoreFiles from "./components/ignore-files.mdx"; + + + +### HTTP Headers + +import HttpHeaders from "./components/http-headers.mdx"; + + + +### Customize a 404/Not Found page + +By default, all unknown paths are automatically rewritten to `/index.html`. However, if you wish to serve a custom `404 Not Found` error when a user attempts to access a non-existent page, you can do so without requiring additional configuration. + +Simply upload a custom `404.html` file to your satellite that should be served from the root path of your site. + +### Redirects + +import Redirects from "./components/redirects.mdx"; + + + +### Rewrites + +import Rewrites from "./components/rewrites.mdx"; + + + +### GZIP + +import Gzip from "./components/gzip.mdx"; + + + +### Encoding types + +import Encoding from "./components/encoding.mdx"; + + + +### iframe + +import IFrame from "./components/iframe.mdx"; + +