> For the complete documentation index, see [llms.txt](https://fusionauth.io/docs/llms.txt)

# Add a Theme to a Kickstart | FusionAuth Docs

Learn how to use Kickstart to create a FusionAuth Instance with a custom theme.

# Add a Theme to a Kickstart

[Edit on GitHub](https://github.com/FusionAuth/fusionauth-site/blob/main/astro/src/content/docs/customize/look-and-feel/advanced-themes/kickstart-custom-theme.mdx)

[View Markdown](https://fusionauth.io/docs/customize/look-and-feel/advanced-themes/kickstart-custom-theme.md)

[FusionAuth Kickstart](https://fusionauth.io/docs/get-started/download-and-install/development/kickstart.md) enables you to spin up a reproducible FusionAuth environment using a template file. This guide will walk you through the process of using Kickstart to set up a FusionAuth instance with a custom theme.

We'll apply a dark theme in place of the default application theme presented in the [5-minute Docker installation guide](https://fusionauth.io/docs/extend/examples/5-minute-intro/5-minute-docker.md). We recommend following the 5-minute Docker installation guide before using this guide to automate the set-up process and apply a custom theme using Kickstart.

## Prerequisites[#](#prerequisites)

You'll need to have Node.js and Docker installed to follow this guide and the 5-minute guide. More information can be found [here](https://fusionauth.io/docs/extend/examples/5-minute-intro/5-minute-docker.md#requirements).

## Getting Started[#](#getting-started)

Once you've completed the steps in the 5-minute guide, we can take a look at the state of the FusionAuth instance you created.

Navigate to Applications and edit the application you created. Go to the OAuth tab to examine the settings that you configured.

![Application settings.](https://fusionauth.io/img/docs/customize/look-and-feel/app-settings.png)

In the 5-minute guide, the **Authorized redirect URLs**, **Logout URL**, **Enabled grants**, and **Require registration** fields were manually entered. We will use Kickstart to automate all of these settings. We will also apply predefined **Client Id** and **Client secret** values to make launching the application easier.

Now, navigate to Users -> Manage for the user that you set up in the 5-minute guide.

![Manage user.](https://fusionauth.io/img/docs/customize/look-and-feel/manageuser.png)

In the 5-minute guide, you created both the user and the FusionAuth registration by manually filling out the registration form. You then added a registration for the user to the application you created. We are going to automate these steps.

Finally, navigate to Customizations -> Themes and preview the FusionAuth theme. The application you created in the 5-minute guide uses the OAuth authorize and OAuth logout pages.

The OAuth authorize template looks like this:

![Preview theme](https://fusionauth.io/img/docs/customize/look-and-feel/preview-oauth.png)

The OAuth logout template looks like this:

![OAuth logout FusionAuth](https://fusionauth.io/img/docs/customize/look-and-feel/preview-oauth-logout.png)

We are going to create a dark theme so these templates that will look like this:

![OAuth authorize Dark](https://fusionauth.io/img/docs/customize/look-and-feel/preview-authorize-dark.png)

![OAuth logout Dark](https://fusionauth.io/img/docs/customize/look-and-feel/preview-logout-dark.png)

## Creating the Files[#](#creating-the-files)

To customize our theme, we'll need to create two files:

*   A CSS file, which we'll use to define the dark theme.
*   A `kickstart.json` file that will enable the automatic configuration of settings.

The requests we add to the `kickstart.json` file will each need a separate JSON file.

If you'd like to skip ahead to the Running Kickstart section, you can [download the completed files here](https://github.com/FusionAuth/fusionauth-example-kickstart/tree/main/theme-css-only).

### The `darkTheme.css` File[#](#the-darkthemecss-file)

The most straightforward way to add a consistent style to your theme is to define a stylesheet using CSS. You can interactively experiment with CSS in your browser to get your application looking the way you want it to.

Let's define one CSS rule together. First, preview the FusionAuth theme and open up the web inspector by right-clicking and selecting "Inspect". Click the Select element button and click the area of the page you would like to style, for example, the `div` element with the class `.panel`.

![Panel background color](https://fusionauth.io/img/docs/customize/look-and-feel/div-panel-bg.png)

This element has a `background` property with a value of `#fff`, or pure white.

Let's change the background from white to black. With the element selected, click the plus + icon and type `background: black`.

![Panel background color](https://fusionauth.io/img/docs/customize/look-and-feel/background-black.png)

We've just defined our first `css` rule. Copy the text that you generated, including the part that the browser made for you when you clicked the plus + icon, into a text editor and save it as `darkTheme.css`, like this:

```css
.panel {
  background: black
}
```

You can keep using this process to add rules to your `darkTheme.css` file until you've got a fully defined style that you're happy with. Feel free to use [this file](https://github.com/FusionAuth/fusionauth-example-kickstart/blob/main/theme-css-only/darkTheme.css) for this tutorial.

Once you have your `darkTheme.css` file, create a folder called `kickstart` and move your `darkTheme.css` file into it.

### The `kickstart.json` File[#](#the-kickstartjson-file)

The `kickstart.json` file allows us to automatically configure everything we need for our application from the moment we first launch it.

Create a file called `kickstart.json` in the `kickstart` folder and copy the following text into it:

```json
{
  "variables":{
    "apiKey" : "#{UUID()}",
    "themeID" : "#{UUID()}",
    "applicationID" : "404e516b-06b8-49da-9c68-c1cd1928c81d",
    "clientSecret" : "RBLhJrfRsa0-YxVPrn_aZfzIGccWyncdvHvDNTy-Hrs",
    "defaultTenantId": "da025934-3ba7-4a13-83f0-aab68c9919b8",
    "userID" : "#{UUID()}"
  },
  "apiKeys": [
    {
      "key": "#{apiKey}"
    }
  ],
  "requests":[
    "&{json/createTheme.json}",
    "&{json/updateTheme.json}",
    "&{json/createApplication.json}",
    "&{json/createUser.json}",
    "&{json/registerUser.json}",
    "&{json/setDefaultTheme.json}"
  ]
}
```

There are three sections in this code: `"variables"`, `"apiKeys"`, and `"requests"`.

The `"variables"` section defines identifiers for the key components of our FusionAuth instance. In this section, `"apiKey"`, `"themeId"`, and `"userId"` are randomly generated UUIDs. We'll use the arbitrary values in `"applicationId"`, `"clientSecret"` and `"defaultTenantId"` later on.

The `"apiKeys"` section defines the key through which our requests will be executed. At least one `"apiKey"` is required for every `kickstart.json` file.

The `"requests"` section defines the API requests that perform our API calls. Each request is stored in a JSON file, which we need to define separately. You can also have them inline, but when you are working with a lot of changes, it is easier to have each change in a separate file.

Let's define these files now.

### The API Request JSON Files[#](#the-api-request-json-files)

Create a subdirectory in the `kickstart` folder called `json`. In the `json` folder, add a file called `createTheme.json` containing the following code:

```json
{
  "method" : "POST",
  "url" : "api/theme/#{themeID}",
  "body" : {
    "sourceThemeId" : "75a068fd-e94b-451a-9aeb-3ddb9a3b5987",
    "theme" : {
      "name" : "Dark Theme"
    }
  }
}
```

This request creates the dark theme. It uses the `"sourceThemeId"` attribute to copy everything from the default FusionAuth theme, the Id of which is always `75a068fd-e94b-451a-9aeb-3ddb9a3b5987`. It also assigns the UUID initialized and contained in the `#{themeID}` variable as this theme's Id by setting it as the resource Id in the path of the URL.

Create a file called `updateTheme.json` and add the following to it:

```json
{
  "method" : "PATCH",
  "url" : "api/theme/#{themeID}",
  "body" : {
    "theme" : {
      "stylesheet" : "@{darkTheme.css}"
    }
  }
}
```

This request applies our `darkTheme.css` stylesheet to the theme we created.

Create a file called `setDefaultTheme.json` and copy the following into it:

```json
{
  "method": "PATCH",
  "url": "/api/tenant/#{defaultTenantId}",
  "body": {
    "tenant": {
      "themeId": "#{themeID}"
    }
  }
}
```

This request sets the dark theme as the theme for the default tenant.

Create a file called `createApplication.json` and copy the following into it:

```json
{
  "method" : "POST",
  "url" : "/api/application/#{applicationID}",
  "body" : {
    "application":{
      "name" : "Kickstart App",
      "oauthConfiguration" : {
        "authorizedRedirectURLs" : [
          "http://localhost:3000/oauth-redirect"
        ],
        "clientId" : "#{applicationID}",
        "clientSecret" : "#{clientSecret}",
        "logoutURL": "http://localhost:3000/logout",
        "enabledGrants": [
          "authorization_code",
          "refresh_token"
        ],
        "requireRegistration" : "true"
      }
    }
  }
}
```

This request creates the application and configures its OAuth settings as they appear in the 5-minute guide.

Create a file called `createUser.json` containing the following:

```json
{
  "method": "POST",
  "url": "/api/user/registration/#{userID}",
  "body": {
    "user": {
      "email": "richard@example.com",
      "password": "password"
    },
    "registration": {
      "applicationId": "#{FUSIONAUTH_APPLICATION_ID}",
      "roles": [
        "admin"
      ]
    }
  }
}
```

This request creates a user and registers the user to the default FusionAuth application. This is necessary to login to the admin panel.

Finally, create a file called `registerUser.json` containing the following:

```json
{
  "method": "POST",
  "url": "/api/user/registration/#{userID}",
  "body": {
    "registration": {
      "applicationId": "#{applicationID}"
    }
  }
}
```

This request adds a registration for the user that we just created to our custom application. This requires a separate request because our initial request used its `"registration"` field for the default application.

With these files, our `kickstart` folder is complete and ready to use. The entire folder can be downloaded [here](https://github.com/FusionAuth/fusionauth-example-kickstart/blob/main/theme-css-only).

## Modifying the Files from the 5-Minute Guide[#](#modifying-the-files-from-the-5-minute-guide)

Next we'll import and modify the files from the 5-minute guide that let us launch and run our FusionAuth instance.

First, download the Docker files.

```bash
curl -o docker-compose.yml https://raw.githubusercontent.com/FusionAuth/fusionauth-containers/main/docker/fusionauth/docker-compose.yml
curl -o .env https://raw.githubusercontent.com/FusionAuth/fusionauth-containers/main/docker/fusionauth/.env
```

To enable Kickstart to run from this `docker-compose.yml` file, we must make some modifications. They are described in detail at [this link](https://fusionauth.io/docs/get-started/download-and-install/docker.md#kickstart) and copied here for your convenience:

*   In the `volumes:` section of the FusionAuth service, add `- ./kickstart:/usr/local/fusionauth/kickstart`.
    
*   Modify `.env` and add the Kickstart configuration variable: `FUSIONAUTH_APP_KICKSTART_FILE=/usr/local/fusionauth/kickstart/kickstart.json`. This path should be what the Docker container expects, not the path on the host.
    
*   Configure `docker-compose.yml` to pass the environment variable set by `.env` to the container. Do this by adding `FUSIONAUTH_APP_KICKSTART_FILE: ${FUSIONAUTH_APP_KICKSTART_FILE}` to the `environment` section of the FusionAuth service.
    

Now download the 5-minute guide files.

```bash
git clone https://github.com/FusionAuth/fusionauth-example-5-minute-guide \
&& cd fusionauth-example-5-minute-guide
```

This folder contains a file called `.env.sample`:

```shell
CLIENT_ID=CHANGEME
CLIENT_SECRET=CHANGEME
BASE_URL=http://localhost:9011
```

Change the **`CLIENT_ID`** and **`CLIENT_SECRET`** so that they match the **`applicationId`** and **`clientSecret`** variables from your `kickstart.json` file. Then save the file as `.env`

```shell
CLIENT_ID=404e516b-06b8-49da-9c68-c1cd1928c81d
CLIENT_SECRET=RBLhJrfRsa0-YxVPrn_aZfzIGccWyncdvHvDNTy-Hrs
BASE_URL=http://localhost:9011
```

## Running Kickstart[#](#running-kickstart)

Once you have completed the steps above, you should have a folder that is structured as follows. We call this folder `Kickstart_Theme`, but you can call it whatever you like.

```plaintext
+ Kickstart_Theme
|
+-- docker-compose.yml
|
+-- fusionauth-example-5-minute-guide
|
+--+ kickstart
   |
   +-- kickstart.json
   |
   +-- darkTheme.css
   |
   +--+ json
      |
      +-- createTheme.json
      |
      +-- updateTheme.json
      |
      +-- createUser.json
      |
      +-- registerUser.json
      |
      +-- createApplication.json
      |
      +-- setDefaultTheme.json
```

To launch the FusionAuth instance, navigate to the `Kickstart_Theme` folder and run the docker compose command.

```bash
docker compose up
```

Once the execution has finished, the newly created FusionAuth instance will be accessible at `http://localhost:9011`.

Login to the FusionAuth instance. The username and password are configured in `kickstart/json/createUser.json`. You can set them to be anything you like, but for this tutorial, they are defined as follows:

```json
"email": "richard@example.com",
"password": "password"
```

Enter these credentials into the login screen to be taken to the admin dashboard.

You can look at Applications , Users , and Customizations -> Themes to verify that all of the settings have been configured correctly.

## Running the Application[#](#running-the-application)

Now that everything is set up and our theme has been applied, we can run the application. Navigate to the `fusionauth-example-5-minute-guide` directory and use `npm` to start the application.

```bash
npm install
npm start
```

Open an incognito window and visit `http://localhost:3000`.

You will be taken to the same landing page that you saw in the 5-minute guide. However, when you click Login this time, you will see your custom theme applied to the OAuth authorize page.

![Dark theme applied](https://fusionauth.io/img/docs/customize/look-and-feel/dark-authorize.png)

Enter the same credentials you used to login to the admin panel and click Logout to see the OAuth logout page.

## Modifying the Default Messages[#](#modifying-the-default-messages)

Let's take it one step further and assume we want to change the content of some of the messages on the OAuth pages. For example, consider the "Forgot your password?" message, which shows up on the OAuth authorize page.

![Forgot password](https://fusionauth.io/img/docs/customize/look-and-feel/forgot-password.png)

Let's say we want to change this to say "Forgot your password? Click here." We can do this by adding a `defaultMessages` property to `json/updateTheme.json`.

The `defaultMessages` string requires at least all of the messages defined in the FusionAuth default shipped messages file to be present, as it updates all messages as a single unit. The easiest way to accomplish this is to create a new file called `defaultMessages.txt` in your `kickstart` folder and copy-paste these messages into it.

The messages can be accessed by editing your custom theme, navigating to the Messages page, and clicking the Edit button.

![Theme messages](https://fusionauth.io/img/docs/customize/look-and-feel/messages.png)

Copy the entire contents of that box into your `defaultMessages.txt` file, find the `forgot-your-password` message (line 65), and modify it to "Forgot your password? Click here."

```json
{
  "method" : "PATCH",
  "url" : "api/theme/#{themeID}",
  "body" : {
    "theme" : {
      "stylesheet" : "@{darkTheme.css}",
      "defaultMessages" : "@{defaultMessages.txt}"
    }
  }
}
```

Kickstart will not run if it sees any users, API keys, or applications in the FusionAuth database. This is to prevent data loss. If you can login to the FusionAuth administrative user interface, Kickstart will not run.

Once you have modified `updateTheme.json`, you will need to clear the volumes created when you launched the FusionAuth instance to allow the Kickstart to rerun. You can do this by executing the following command (This will totally destroy all data stored in the instance):

```bash
docker compose down -v
```

When you relaunch the instance using the `docker compose up` command, the result will be as below with the updated message:

![Updated message](https://fusionauth.io/img/docs/customize/look-and-feel/updated-message.png)

## Conclusion[#](#conclusion)

This guide has shown you how to use Kickstart to launch a reproducible FusionAuth instance with a custom theme. The complete set of files for this project can be found [here](https://github.com/FusionAuth/fusionauth-example-kickstart) in the directory called `theme-css-only`.

Some suggestions for further reading are as follows:

*   [General documentation on Themes](https://fusionauth.io/docs/customize/look-and-feel.md)
*   [API-specific documentation on Themes](https://fusionauth.io/docs/apis/themes.md)