"><linkrel=canonicalhref=https://jpanther.github.io/congo/docs/hosting-deployment/><linkrel=apple-touch-iconsizes=180x180href=/congo/apple-touch-icon.png><linkrel=icontype=image/pngsizes=32x32href=/congo/favicon-32x32.png><linkrel=icontype=image/pngsizes=16x16href=/congo/favicon-16x16.png><linkrel=manifesthref=/congo/site.webmanifest><metaproperty="og:title"content="Hosting & Deployment"><metaproperty="og:description"content="Learn how to deploy a Congo site."><metaproperty="og:type"content="article"><metaproperty="og:url"content="https://jpanther.github.io/congo/docs/hosting-deployment/"><metaproperty="article:section"content="docs"><metaproperty="article:published_time"content="2020-08-07T00:00:00+00:00"><metaproperty="article:modified_time"content="2020-08-07T00:00:00+00:00"><metaname=twitter:cardcontent="summary"><metaname=twitter:titlecontent="Hosting & Deployment"><metaname=twitter:descriptioncontent="Learn how to deploy a Congo site."><scripttype=application/ld+json>{"@context":"https://schema.org","@type":"Article","articleSection":"Documentation","name":"Hosting \u0026 Deployment","headline":"Hosting \u0026 Deployment","description":"Learn how to deploy a Congo site.","abstract":"Congo is designed to be flexible in almost any deployment scenario. Learn more about how to deploy your project to some common hosting platforms.","inLanguage":"en-AU","url":"https:\/\/jpanther.github.io\/congo\/docs\/hosting-deployment\/","author":{"@type":"Person","name":"Congo"},"copyrightYear":"2020","dateCreated":"2020-08-07T00:00:00\u002b00:00","datePublished":"2020-08-07T00:00:00\u002b00:00","dateModified":"2020-08-07T00:00:00\u002b00:00","keywords":["hosting","deployment","docs","github","netlify","render"],"mainEntityOfPage":"true","wordCount":"837"}</script><metaname=authorcontent="Congo"><linkhref=https://twitter.com/rel=me><linkhref=https://facebook.com/rel=me><linkhref=https://linkedin.com/rel=me><linkhref=https://youtube.com/rel=me></head><bodyclass="m-auto flex h-screen max-w-7xl flex-col bg-neutral px-6 text-lg leading-7 text-neutral-900 sm:px-14 md:px-24 lg:px-32 dark:bg-neutral-800 dark:text-neutral"><divid=the-topclass="absolute flex self-center"><aclass="-translate-y-8 rounded-b-lg bg-primary-200 px-3 py-1 text-sm focus:translate-y-0 dark:bg-neutral-600"href=#main-content><spanclass="pe-2 font-bold text-primary-600 dark:text-primary-400">↓</span>Skip to main content</a></div><headerclass="py-6 font-semibold text-neutral-900 print:hidden sm:py-10 dark:text-neutral"><navclass="flex items-start justify-between sm:items-center"><divclass="flex flex-row items-center"><aclass="decoration-primary-500 hover:underline hover:decoration-2 hover:underline-offset-2"rel=mehref=/congo/>Congo</a></div><ulclass="flex list-none flex-col text-end sm:flex-row"><liclass="group mb-1 sm:mb-0 sm:me-7 sm:last:me-0.5"><ahref=/congo/docs/title><spanclass="decoration-primary-500 group-hover:underline group-hover:decoration-2 group-hover:underline-offset-2">Docs</span></a></li><liclass="group mb-1 sm:mb-0 sm:me-7 sm:last:me-0.5"><ahref=/congo/samples/title><spanclass="decoration-primary-500 group-hover:underline group-hover:decoration-2 group-hover:underline-offset-2">Samples</span></a></li><liclass="group mb-1 sm:mb-0 sm:me-7 sm:last:me-0.5"><ahref=/congo/users/title><spanclass="decoration-primary-500 group-hover:underline group-hover:decoration-2 group-hover:underline-offset-2">Users</span></a></li><liclass="group mb-1 sm:mb-0 sm:me-7 sm:last:me-0.5"><ahref=https://github.com/jpanther/congotitletarget=_blank><spanclass="group-dark:hover:text-primary-400 transition-colors group-hover:text-primary-600"><spanclass="icon relative inline-block px-1 align-text-bottom"><svgxmlns="http://www.w3.org/2000/svg"viewBox="0 0 496 512"><pathfill="currentcolor"d="M165.9397.4c02-2.33.6-5.23.6-3.3.3-5.6-1.3-5.6-3.6.0-22.3-3.65.2-3.63-.35.61.35.63.6zm-31.1-4.5c-.721.34.34.34.92.615.6.06.2-2s-1.3-4.3-4.3-5.2c-2.6-.7-5.5.3-6.22.3zm44.2-1.7c-2.9.7-4.92.6
<spanclass=mb-[2px]><ahref=https://github.com/jpanther/congo/tree/dev/exampleSite/content/docs/hosting-deployment/index.mdclass="text-lg hover:text-primary-500"rel="noopener noreferrer"target=_blanktitle="Edit content"><spanclass="icon relative inline-block px-1 align-text-bottom"><svgxmlns="http://www.w3.org/2000/svg"viewBox="0 0 512 512"><pathfill="currentcolor"d="M490.3 40.4c21.9 21.87 21.9 57.33.0 79.2l-30 30.1-98-97.98 30.1-30.06C414.3-.2135 449.7-.2135 471.6 21.66L490.3 40.4zM172.4 241.7 339.7 74.34l98 97.96L270.3 339.6C264.2 345.8 256.7 350.4 248.4 353.2l-88.8 29.6C150.1 385.6 141.5 383.4 135 376.1 128.6 370.5 126.4 361 129.2 352.4l29.6-88.8C161.6 255.3 166.2 247.8 172.4 241.7v0zM192 63.1c17.7.0 32 15.23 32 32 0 18.6-14.3 32-32 32H96c-17.67.0-32 15.2-32 32V416c0 17.7 14.33 32 32 32H352c17.7.0 32-14.3 32-32V319.1c0-16.8 14.3-32 32-32s32 15.2 32 32V416c0 53-43 96-96 96H96c-53.02.0-96-43-96-96V159.1c0-53 42.98-96 96-96h96z"/></svg></span></a></span></div></div></header><sectionclass="prose mt-0 flex max-w-full flex-col dark:prose-invert lg:flex-row"><divclass="order-first px-0 lg:order-last lg:max-w-xs lg:ps-8"><divclass="toc pe-5 print:hidden lg:sticky lg:top-10"><detailsopenclass="-ms-5 mt-0 overflow-hidden rounded-lg ps-5"><summaryclass="block cursor-pointer bg-neutral-100 py-1 ps-5 text-lg font-semibold text-neutral-800 dark:bg-neutral-700 dark:text-neutral-100 lg:hidden">Table of Contents</summary><divclass="border-s border-dotted border-neutral-300 py-2 ps-5 dark:border-neutral-600"><navid=TableOfContents><ul><li><ahref=#github-pages>GitHub Pages</a></li><li><ahref=#netlify>Netlify</a></li><li><ahref=#render>Render</a></li><li><ahref=#cloudflare-pages>Cloudflare Pages</a></li><li><ahref=#shared-hosting-vps-or-private-web-server>Shared hosting, VPS or private web server</a></li></ul></nav></div></details></div></div><divclass="min-h-0 min-w-0 max-w-prose grow"><p>There are many ways to deploy your Hugo website built with Congo. The theme is designed to be flexible in almost any deployment scenario.</p><p>Congo is built using relative URLs throughout the theme. This enables sites to easily be deployed to sub-folders and hosts like GitHub Pages. There’s usually no special configuration required for this to work as long as the <code>baseURL</code> parameter has been configured in the <code>config.toml</code> file.</p><p>The official Hugo <ahref=https://gohugo.io/hosting-and-deployment/target=_blankrel=noreferrer>Hosting and Deployment</a> docs are the best place to learn how to deploy your site. The sections below contain some specific theme configuration details that can help you deploy smoothly with certain providers.</p><p><strong>Choose your provider:</strong></p><ul><li><ahref=#github-pages>GitHub Pages</a></li><li><ahref=#netlify>Netlify</a></li><li><ahref=#render>Render</a></li><li><ahref=#cloudflare-pages>Cloudflare Pages</a></li><li><ahref=#shared-hosting-vps-or-private-web-server>Shared hosting, VPS or private web server</a></li></ul><hr><h2id=github-pagesclass="relative group">GitHub Pages <spanclass="absolute top-0 w-6 transition-opacity opacity-0 -start-6 not-prose group-hover:opacity-100"><aclass="group-hover:text-primary-300 dark:group-hover:text-neutral-700"style=text-decoration-line:none!importanthref=#github-pagesaria-label=Anchor>#</a></span></h2><p>GitHub allows hosting on <ahref=https://docs.github.com/en/pages/getting-started-with-github-pages/about-github-pagestarget=_blankrel=noreferrer>GitHub Pages</a> using Actions. To enable this functionality, enable Pages on your repo and create a new Actions workflow to build and deploy your site.</p><p>The file needs to be in YAML format, placed within the <code>.github/workflows/</code> directory of your GitHub repository and named with a <code>.yml</code> extension.</p><divclass="flex rounded-md bg-primary-100 px-4 py-3 dark:bg-primary-900"><spanclass="pe-3 text-primary-400"><spanclass="icon relative inline-block px-1 align-text-bottom"><svgxmlns="http://www.w3.org/2000/svg"viewBox="0 0 512 512"
</span></span><spanclass=dark:text-neutral-300><strong>Important:</strong> Ensure you set the correct branch name under <code>branches</code> and in the deploy step <code>if</code> parameter to the source branch used in your project.</span></div><divclass=highlight><pretabindex=0class=chroma><codeclass=language-yamldata-lang=yaml><spanclass=line><spanclass=cl><spanclass=c># .github/workflows/gh-pages.yml</span><spanclass=w>
</span></span></span></code></pre></div><p>Push the config file to GitHub and the action should automatically run. It may fail the first time and you’ll need to visit the <strong>Settings > Pages</strong> section of your GitHub repo to check the source is correct. It should be set to use the <code>gh-pages</code> branch.</p><figure><picture><sourcesrcset="/congo/docs/hosting-deployment/github-pages-source_hu82845702bc541a9fb3f6cd5fc157ad89_175631_330x0_resize_q75_h2_box.webp330w,/congo/docs/hosting-deployment/github-pages-source_hu82845702bc541a9fb3f6cd5fc157ad89_175631_660x0_resize_q75_h2_box.webp660w
,/congo/docs/hosting-deployment/github-pages-source_hu82845702bc541a9fb3f6cd5fc157ad89_175631_1320x0_resize_q75_box.jpg 1320w" sizes=100vw></picture></figure><p>You should also visit the <strong>Settings > Actions > General</strong> section and check that the workflow permissions allow actions to make changes to your repo.</p><figure><picture><sourcesrcset="/congo/docs/hosting-deployment/github-workflow-permissions_hu82845702bc541a9fb3f6cd5fc157ad89_349304_330x0_resize_q75_h2_box.webp330w,/congo/docs/hosting-deployment/github-workflow-permissions_hu82845702bc541a9fb3f6cd5fc157ad89_349304_660x0_resize_q75_h2_box.webp660w
,/congo/docs/hosting-deployment/github-workflow-permissions_hu82845702bc541a9fb3f6cd5fc157ad89_349304_1320x0_resize_q75_box.jpg 1320w" sizes=100vw></picture></figure><p>Once the settings are configured, re-run the action and the site should build and deploy correctly. You can consult the actions log to check everything deployed successfully.</p><h2id=netlifyclass="relative group">Netlify <spanclass="absolute top-0 w-6 transition-opacity opacity-0 -start-6 not-prose group-hover:opacity-100"><aclass="group-hover:text-primary-300 dark:group-hover:text-neutral-700"style=text-decoration-line:none!importanthref=#netlifyaria-label=Anchor>#</a></span></h2><p>To deploy to <ahref=https://www.netlify.comtarget=_blankrel=noreferrer>Netlify</a>, create a new continuous deployment site and link it to your source code. The build settings can be left blank in the Netlify UI. You will only need to configure the domain you’ll be using.</p><figure><picture><sourcesrcset="/congo/docs/hosting-deployment/netlify-build-settings_hu2dd769ba6150bc188f19ac555e8a2ca4_73715_330x0_resize_q75_h2_box.webp330w,/congo/docs/hosting-deployment/netlify-build-settings_hu2dd769ba6150bc188f19ac555e8a2ca4_73715_660x0_resize_q75_h2_box.webp660w
,/congo/docs/hosting-deployment/netlify-build-settings.jpg 958w" sizes=100vw></picture></figure><p>Then in the root of your site repository, create a <code>netlify.toml</code> file:</p><divclass=highlight><pretabindex=0class=chroma><codeclass=language-tomldata-lang=toml><spanclass=line><spanclass=cl><spanclass=c># netlify.toml</span>
</span></span><spanclass=line><spanclass=cl><spanclass=nx>command</span><spanclass=p>=</span><spanclass=s2>"hugo mod get -u && hugo --gc --minify -b $URL"</span>
</span></span><spanclass=line><spanclass=cl><spanclass=nx>TZ</span><spanclass=p>=</span><spanclass=s2>"UTC"</span><spanclass=c># Set to preferred timezone</span>
</span></span></code></pre></div><p>This configuration assumes you are deploying Congo as a Hugo module. If you have installed the theme using another method, change the build command to simply <code>hugo --gc --minify -b $URL</code>.</p><p>When you push the config file to your repo, Netlify should automatically deploy your site. You can check the deploy logs in the Netlify UI to check for any errors.</p><h2id=renderclass="relative group">Render <spanclass="absolute top-0 w-6 transition-opacity opacity-0 -start-6 not-prose group-hover:opacity-100"><aclass="group-hover:text-primary-300 dark:group-hover:text-neutral-700"style=text-decoration-line:none!importanthref=#renderaria-label=Anchor>#</a></span></h2><p>Deploying to <ahref=https://render.comtarget=_blankrel=noreferrer>Render</a> is very straightforward and all configuration is via the Render UI.</p><p>Create a new <strong>Static Site</strong> and link it to your project’s code repository. Then simply configure the build command to be <code>hugo --gc --minify</code> and publish directory to be <code>public</code>.</p><figure><picture><sourcesrcset="/congo/docs/hosting-deployment/render-settings_hu2dd769ba6150bc188f19ac555e8a2ca4_96294_330x0_resize_q75_h2_box.webp330w,/congo/docs/hosting-deployment/render-settings_hu2dd769ba6150bc188f19ac555e8a2ca4_96294_660x0_resize_q75_h2_box.webp660w
,/congo/docs/hosting-deployment/render-settings.jpg 1256w" sizes=100vw></picture></figure><p>The site will automatically build and deploy whenever you push a change to your repo.</p><h2id=cloudflare-pagesclass="relative group">Cloudflare Pages <spanclass="absolute top-0 w-6 transition-opacity opacity-0 -start-6 not-prose group-hover:opacity-100"><aclass="group-hover:text-primary-300 dark:group-hover:text-neutral-700"style=text-decoration-line:none!importanthref=#cloudflare-pagesaria-label=Anchor>#</a></span></h2><p>Cloudflare offers the <ahref=https://pages.cloudflare.com/target=_blankrel=noreferrer>Pages</a> service that can host Hugo blogs. It builds the site from a git repository and then hosts it on Cloudflare’s CDN. Follow their <ahref=https://developers.cloudflare.com/pages/framework-guides/deploy-a-hugo-sitetarget=_blankrel=noreferrer>Hugo deployment guide</a> to get started.</p><p>The Rocket Loader™ feature offered by Cloudflare tries to speed up rendering of web pages with JavaScript, but it breaks the appearance switcher in the theme. It can also cause an annoying light/dark screen flash when browsing your site due to scripts loading in the wrong order.</p><p>This problem can be fixed by disabling it:</p><ul><li>Go to the <ahref=https://dash.cloudflare.comtarget=_blankrel=noreferrer>Cloudflare dashboard</a></li><li>Click on your domain name in the list</li><li>Click <em>Optimization</em> in the <em>Speed</em> section</li><li>Scroll down to <em>Rocket Loader™</em> and disable it</li></ul><p>Hugo sites built with Congo still load very quickly, even with this feature disabled.</p><h2id=shared-hosting-vps-or-private-web-serverclass="relative group">Shared hosting, VPS or private web server <spanclass="absolute top-0 w-6 transition-opacity opacity-0 -start-6 not-prose group-hover:opacity-100"><aclass="group-hover:text-primary-300 dark:group-hover:text-neutral-700"style=text-decoration-line:none!importanthref=#shared-hosting-vps-or-private-web-serveraria-label=Anchor>#</a></span></h2><p>Using traditional web hosting, or deploying to your own web server, is as simple as building your Hugo site and transferring the files to your host.</p><p>Make sure that the <code>baseURL</code> parameter in <code>config.toml</code> is set to the full URL to the root of your website (including any sub domains or sub-folders).</p><p>Then build your site using <code>hugo</code> and copy the contents of the output directory to the root of your web server and you will be ready to go. By default, the output directory is named <code>public</code>.</p><p><em>If you need a hosting provider, check out <ahref="https://www.vultr.com/?ref=8957394-8H"target=_blankrel=noreferrer>Vultr</a> or <ahref=https://m.do.co/c/36841235e565target=_blankrel=noreferrer>DigitalOcean</a>. Signing up using these affiliate links will give you up to $100 in free credit so you can try the service.</em></p></div></section><footerclass="max-w-prose pt-8 print:hidden"><divclass=pt-8><hrclass="border-dotted border-neutral-300 dark:border-neutral-600"><divclass="flex justify-between pt-3"><span><aclass="group flex"href=/congo/docs/advanced-customisation/><spanclass="me-2 text-neutral-700 transition-transform group-hover:-translate-x-[2px] group-hover:text-primary-600 dark:text-neutral dark:group-hover:text-primary-400"><spanclass="ltr:inline rtl:hidden">←</span><spanclass="ltr:hidden rtl:inline">→</span></span>
