> For the complete documentation index, see [llms.txt](https://docs.civictheme.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.civictheme.io/playbook/govcms/01-installation.md). # Installation This chapter walks your team through getting CivicTheme installed and running on a GovCMS SaaS project. By the end, you will have CivicTheme enabled, a sub-theme generated, front-end assets built, and the site ready for customisation. GovCMS SaaS does not support installing themes via Composer, so CivicTheme is installed as a custom theme. An automated script handles the heavy lifting, but a manual path is available if you need more control. ## Prerequisites * [ ] Access to the GovCMS GitLab project * [ ] A support ticket actioned to enable config imports * [ ] Your user added with the administrator role in production * [ ] All [GovCMS SaaS required software](https://github.com/govCMS/GovCMS/wiki/1.1-Local-setup#dependencies) installed (Docker, Ahoy, tar, curl, Bash) * [ ] NodeJS 22+ and NPM 10+ available on your machine * [ ] A GovCMS project already set up and installed locally (`ahoy install` completed) ## Step 1: Choose your installation method | Method | Best for | Time | | --------- | -------------------------------------- | ------------ | | Automated | New projects, standard setups | \~15 minutes | | Manual | Existing projects, custom requirements | \~45 minutes | There are automated steps (a bash script that automates the steps and a follow along manual step process. For an overview of both methods and when to choose each, see the [GovCMS SaaS installation overview](/installation/govcms-saas.md). ## Step 2: Run the installation ### Option A: Automated installation (recommended) The automated script downloads CivicTheme, configures modules, removes GovCMS default content types, generates your sub-theme, and optionally provisions content — all in one command. The script arguments, flags, download instructions, and example commands are documented in the [automated installation guide](/installation/govcms-saas/govcms-saas-automated.md). > **Naming tip**: Name your sub-theme after the site, not after CivicTheme. Avoid including "civic" or "civictheme" in the machine name — it creates confusion when maintaining the theme later. ### Option B: Manual installation If you need more control, the manual process walks through each step individually: downloading CivicTheme, enabling modules, removing GovCMS default content types via the `civictheme_govcms` helper module, generating the sub-theme, and building assets. The full step-by-step process is covered in the [manual installation guide](/installation/govcms-saas/govcms-saas-manual.md). ## Step 3: Build front-end assets After installation (automated or manual), build your sub-theme's CSS, JavaScript, and assets: ```bash cd themes/ nvm use npm install npm run build ``` Verify that the `themes//dist` directory was created. Navigate to your site in the browser and confirm that default CivicTheme styling is applied. ### Commit built assets GovCMS SaaS requires built assets to be committed to the repository. But it is important not to commit your `node_modules` and other developer tools. **Review** [**committing built assets**](/installation/govcms-saas/govcms-saas-manual.md#commit-built-assets) **for managing your code repository.** ## Step 4: Provision content CivicTheme includes pre-configured blocks, menus, and configuration entities that set up the default site structure (header, footer, navigation, etc.). Unless a database forklift is being undertaken, the provisioning needs to happen **twice** — once locally to capture the configuration, and once in production to populate it with content. Both are triggered via the **Provision content** button at `/admin/appearance/settings/`. The full provisioning workflow, what gets created, how to avoid content forklifts, and troubleshooting are documented in the [GovCMS content provisioning guide](/installation/govcms-saas/govcms-content-provisioning.md). ## Step 5: Verify the installation After provisioning, your site should match the [default CivicTheme site](https://default.civictheme.io/) (without homepage content). Check that: * [ ] The header displays with the CivicTheme logo and navigation * [ ] The footer displays with default blocks (social links, footer navigation, acknowledgement, copyright) * [ ] The site responds correctly on mobile (navigation collapses to mobile menu) * [ ] The admin theme is accessible at `/admin` ## Troubleshooting For common installation issues (content not appearing, styling not applied, provisioning button missing), see the troubleshooting section in the [GovCMS SaaS installation reference](/installation/govcms-saas.md#troubleshooting). ## Where to get help CivicTheme provides multiple support channels for installation issues. For all support options, see [Getting help](/getting-started/getting-help.md). ## Next step With CivicTheme installed and your sub-theme generated, the next step is to understand the sub-theme structure and set up your local development workflow. Continue to [Chapter 2: Setting Up Your Sub-Theme](/playbook/govcms/02-sub-theme-setup.md). --- # 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, and the optional `goal` query parameter: ``` GET https://docs.civictheme.io/playbook/govcms/01-installation.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. 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.