Installation

Follow this guide to install Emporium on your Kubernetes cluster using helm.

DANGER

Disclaimer: By installing Emporium, you acknowledge and accept that the process and its outcomes are solely your responsibility. Emporium is currently in its alpha stage and may contain bugs. We do not assume liability for any issues, data loss, or other adverse events that may occur. Use at your own risk.

Install with emp cli

We recommend using the emp cli to install Emporium.

Grab the emp cli with this command:

curl https://cli.emporium.build/ | sh

Execute emp install and follow the instructions:

➜  ~ emp install   
✨ Cluster detected: supercluster
✗ Is there an existing Authentik instance you wish to integrate with Emporium?: 
What FQDN should be used to access Authentik? (e.g., id.example.org): id.emporium.hair
What FQDN should be used for Emporium's access? (e.g., emporium.example.org): emporium.hair
Which Kubernetes Namespace do you prefer for installing Emporium? (default: emporium): emporium
Which Kubernetes Namespace do you prefer for installing Emporium? (default: emporium): emporium
⏳ Installing Emporium on cluster supercluster. This might take a few minutes...
✅ Emporium installation complete on supercluster.

Access Emporium:

Emporium URL: https://emporium.hair
Authentik Username: akadmin
Authentik Bootstrap Password: Z3i1alwkfU0OaM2PS4YDI42XkdHlYp3ro

The 'akadmin' user is for initial testing only. Create a personal account or configure a social login for production use.
Change the 'akadmin' password immediately after first login.

You might encounter a temporary DNS error as the newly created domain resolves. Please wait a few minutes and try again.
If you see an empty Emporium home screen, the installation is successful!
Follow the Emporium Docs to add repositories: https://emporium.build/docs/guides/configure-repositories.html

Install with Helm Chart

To install Emporium, run the following command. Make sure to replace the hostnames with your own domains.

Prerequesites

• Make sure you have helm and kubectl installed on your system.
• Cert manager has to be installed and configured on your cluster.

Create Namespace

While not strictly necessary, it's recommended to create a separate namespace for Emporium.

kubectl create ns emporium

INFO

The complete installation usually takes about 5 minutes.

helm install emporium emporium -n emporium --repo https://emporium.helm.pkg.emporium.rocks -f - << EOF
panel:
  ingress:
    host: "emporium.build"
releaseChannel: "stable"
identity:
  authentik:
    host: "id.emporium.build"

authentik:
  server:
    ingress:
      hosts:
      - id.emporium.build
      pathType: Prefix
      paths:
      - /
      tls:
      - hosts:
        - id.emporium.build
        secretName: authentik-tls
EOF

Already have an Authentik instance?

By default, the Emporium helm chart comes bundeled with an Authentik instance for identity management.

If you want to connect to a different Authentik instance, you can disable the included instance by setting authentik.enabled to false.

Then set the identity.authentik.hostname and identity.authentik.token variables.

Verify Installation

After the installation suceeds, helm will print out the URLs where your fresh Emporium instance will be accessible.

...
Access your freshly installed Emporium via the following URL:
https://[emporium.example.org]
...

On visiting this URL you will be greeted by a login page from Authentik. If you get a DNS error, please note that the DNS resolution of the freshly created domain might take some time. Patience is your friend.

For initial testing purposes, you can use the akadmin user to log in. Make sure to create your personal user or configure a social login provider for production use.

To get the password for akadmin, execute the following command.

kubectl get secret \
  --namespace emporium \
  -o jsonpath="{.data.AUTHENTIK_BOOTSTRAP_PASSWORD}" \
  emporium-authentik | base64 --decode; echo

INFO

It's recommended to change the password of akadmin after you logged in for the first time.

Once logged in, you should see an emplty Emporium home screen. If that is the case, you successfully installed Emporium.

Congratulations! 🎉

Uninstallation

Follow these steps to properly uninstall Emporium and all installed apps from your cluster.

Uninstalls Apps

As the first step, make sure to uninstall all apps via Emporium UI before proceeding. Installed apps won't be automatically removed upon Emporium's uninstallation.

Helm Uninstall

Run the following command to uninstall Emporium.

helm uninstall emporium -n emporium

INFO

Make sure you replace the helm release name and namespace with values matching your installation.

To completely get rid of all resources created by the Emporium helm chart, it's recommended to delete the corresponding namespace. You can do that by running the following command.

kubectl delete ns emporium