> For the complete documentation index, see [llms.txt](https://developer.harness.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developer.harness.io/harness-solutions-factory/new-to-hsf/hsf-deployment-guide.md).

# Self Deployment of Harness Solutions Factory

Deploy HSF in your account.

Deploy Harness Solutions Factory (HSF) into your own account with OpenTofu or mise. A professional services engagement can run this deployment for you. The steps below are for a self-managed install.

***

## What you will learn from this topic

* **Account checks:** Which modules, tokens, and policy conditions to confirm before the first apply.
* **Variable file:** Which `terraform.tfvars` values the pilot-light deployment requires.
* **First apply:** How to deploy with local state, then move that state into the Harness backend.
* **Unpack pipeline:** How to finish registration of workflows, workspaces, and a verification provision.

***

## Before you begin <a href="#before-you-begin" id="before-you-begin"></a>

Before HSF can be deployed, confirm the following:

* IaCM is required. Depending on your architecture and the operating mode you choose, you may also need IDP and Harness Code Repository. If your account is not licensed for the modules you need, Harness can provide a limited license covering HSF usage for managing Harness entities. Restrictions may apply.
* You have an account with admin-level permissions, or can coordinate with someone who does to generate a temporary Personal Access Token (PAT). This token is used to create account-level resources during deployment and can be deleted afterward. Go to [RBAC in Harness](https://developer.harness.io/docs/platform/role-based-access-control/rbac-in-harness) to review how account admin access is assigned.
* No account-level OPA policies are in place that would block pipeline execution.
* You have OpenTofu installed locally, or the mise environment configured.

{% hint style="info" %}
**Professional services deployments**

If you have a professional services engagement, your account team will assist with this deployment and use our instance of HSF to deploy HSF.
{% endhint %}

***

## Deploy HSF on your own <a href="#deploy-hsf-on-your-own" id="deploy-hsf-on-your-own"></a>

1. Clone the [HSF 2.5 repository](https://github.com/harness/Harness-Solutions-Factory) to your local machine.
2. In the `pilot-light` directory, locate the **Terraform examples file** (`terraform.tfvars.example`). Save a copy without the `.example` extension.
3. Open the file and fill in the following required values:
   * **harness\_platform\_url :** your Harness platform URL. This must be changed if there is a vanity URL
   * **harness\_platform\_account :** your Harness account ID
   * **harness\_platform\_key :** a Harness API key with appropriate permissions
   * **initial\_admin\_user:** email address for admin user. If left blank, no user will be added to the HSF Admin group, so do not skip it.
4. The following variables have defaults but you should review them:

| Variable                  | Default | Notes                                                                                                                  |
| ------------------------- | ------- | ---------------------------------------------------------------------------------------------------------------------- |
| `store_backend`           | `false` | Controls whether Terraform state is pushed to the remote backend. Leave `false` for the first run.                     |
| `should_unpack`           | `false` | Must be set to `true` for the initial deployment. Set back to `false` afterward, because it is a one-time operation.   |
| `should_setup_custom_tpl` | `false` | Enable creating local harness code repo for custom configurations. This requires Harness Code Repository to be enabled |
| `should_use_harness_idp`  | `true`  | Toggle IDP support on or off as needed. This requires Harness Internal Developer Portal to be enabled                  |

5. Review and set **SCM Source Configurations:** By default, the deployment pulls from the official Harness GitHub repository. If you want to use a custom connector (e.g., your own GitHub Enterprise or a different registry):
   1. Set `hsf_source_connector` to your connector's identifier ex: account.github
   2. Update the `hsf_source_fetch_type` to `branch`, `tag`, or `SHA` accordingly
   3. **Going forward, HSF 2.5 defaults to pinning by tag.** This is the recommended approach for controlled upgrades
6. Review and set **Kubernetes Configurations:** If you are using Kubernetes set the variables accordingly
7. Review and set **HSF Plugin Configurations:** If you are using Artifactory or Nexus instead of Docker Hub, set the connector and update each image reference to point to your internal registry. Use the fully qualified hostname. Go to [Host Your Own Images](/harness-solutions-factory/use-hsf/configurations/hosting-your-own-images.md) to review registry configuration.
8. Save the changes
9. With `store_backend = false` and `should_unpack = true`, run the deployment
   * If using mise: `mise deploy`
   * If using tofu:

     ```bash
     tofu init
     tofu plan
     tofu apply
     ```

The deployment will create all infrastructure resources. You can flip back to your Harness account and watch the **Solutions Factory project** appear under Projects. Once visible, verify:

* The config is pointing to the correct GitHub connector
* The git tag/branch is set as expected
* Kubernetes and other connectors are populated under the workspace's variables

{% hint style="info" %}
**SCM variables stay in Configurations**

The **SCM Source Configurations** variables are not copied to Pilot Light variables. Manage them in Configurations only.
{% endhint %}

10. Once the first deployment completes successfully, you will notice that the Harness Pilot Light workspace contains no state file. That is linked to the `store_backend` variable. To migrate the Terraform state to the remote backend so it is managed from within Harness going forward:
    * In your variables file, set `store_backend = true`
    * Run deploy again to generate the backend configuration file:
      * `mise deploy` or `tofu apply`
    * Run init to copy the local state to the remote:
      * `mise init`

When prompted **"Do you want to copy your local state to the remote?"**, enter **yes**.

Go back to your Harness workspace and refresh the state view. You now see the state file uploaded and the workspace showing as locked, which is the expected behavior after a local CLI push. Click **Unlock**.

{% hint style="info" %}
The backend config file and local repository do not need to be maintained after this point. All future runs should be executed directly from Solutions Factory.
{% endhint %}

11. Run the `Unpack Solutions Factory` pipeline. In the `Pilot Light` project, navigate to **Pipelines**, select the Unpack pipeline, then click **Run**.

Once complete:

* The Solutions Factory will be deployed
* IDP workflows will be registered from the configured remote repository
* New workspaces will be created using the connector configuration you set
* Run one final quick provision from Solutions Factory to confirm the environment is stable and self-contained
  * Run Managed Pilot Light
  * Run Deploy Solutions Factory

{% hint style="info" %}
**Run later updates from Solutions Factory**

All updates are run through Solutions Factory, not through the local repository.
{% endhint %}

***

## Troubleshooting

### Solutions Factory project does not appear

The first apply creates the **Solutions Factory** project. If it does not show under Projects, confirm the API key can create account-level resources and that no account-level Open Policy Agent (OPA) policy is blocking pipeline execution. Generate a new temporary PAT with an account admin if the key is limited, then run apply again.

### Pilot Light workspace has no state file

That is expected while `store_backend` is `false`. After the first deployment succeeds, set `store_backend = true`, run deploy again, then run init and copy local state to the remote backend. Refresh the workspace state view after the copy completes.

### Workspace stays locked after the state upload

A local CLI push leaves the workspace locked. Open the workspace state view and click **Unlock** before the next run from Solutions Factory.

***

## Next steps <a href="#next-steps" id="next-steps"></a>

Your Solutions Factory deployment is live and managing its own state. Continue with the following:

* [How HSF works](/harness-solutions-factory/new-to-hsf/how-hsf-works.md): Understand the Pilot Light and Solutions Factory relationship you deployed.
* [Mini Factory and Factory Floor](/harness-solutions-factory/use-hsf/mini-factory-and-factory-floor.md): Start provisioning projects from the factory.
* [Host Your Own Images](/harness-solutions-factory/use-hsf/configurations/hosting-your-own-images.md): Point HSF plugin images at your own registry.

{% @harness-feedback/feedback %}