Skip to main content

Kubernetes

Overview​

This guide offers a comprehensive overview of installing the Appcircle chart. While the provided default values are suitable for initial trials, they are not recommended for production environments.

For production deployments, it is essential to review the detailed descriptions and optional sections to ensure a secure and reliable setup. This document supports both trial and production installations.

Prerequisites​

To complete this guide, you must have the following:

1. Domain Name​

A main domain name, which will have subdomains, is required for the Appcircle server.

note

In this documentation, we will use appcircle.spacetech.com as an example main domain and spacetech as an example organization name.

Click to view more details about domain name prerequisite.

By default, Appcircle uses seven subdomains. These subdomains are:

  1. api.appcircle.spacetech.com
  2. auth.appcircle.spacetech.com
  3. dist.appcircle.spacetech.com
  4. hook.appcircle.spacetech.com
  5. resource.appcircle.spacetech.com
  6. my.appcircle.spacetech.com
  7. kvs.appcircle.spacetech.com

Upon completing the deployment of the Appcircle server, you will need to create DNS records based on the Ingress objects created in Kubernetes.

2. SSL Certificate​

An SSL certificate is required to deploy the Appcircle server for production environments.

You can skip SSL certificate if you are deploying Appcircle server for trial purposes.

Click to view more details about SSL certificate prerequisite.

  • The SSL certificate private key shouldn't be password protected.

  • The SSL certificate should be in PEM format.

  • Ensure the one certificate covers all the subdomains in the domain name section.

  • Make sure to configure the Appcircle server with a fullchain certificate, which should include the leaf (or app) certificate, intermediate certificates, and the root certificate.

tip

You can use a wildcard certificate to cover all the subdomains, simplifying the certificate management process. For example, a wildcard certificate for *.appcircle.spacetech.com will be enough.

caution

If you use a domain like appcircle.spacetech.com, it will have two levels of subdomains. Ensure that both your DNS provider and SSL certificate provider support multi-level subdomains for proper configuration.

3. Kubernetes Cluster​

A Kubernetes cluster is required to install the Appcircle server using Helm.

Minimum hardware requirements for enterprise installation:

  • Node(s) with x86_64 architecture
  • 8 CPUs
  • 16 GB RAM
  • 50 GB Disk per node
tip

The required storage size for the Appcircle server depends significantly on the size of the artifacts (APK, IPA, cache).

Click to view more details about Kubernetes cluster prerequisite.

Recommended hardware requirements for enterprise installation:

  • Nodes with x86_64 architecture
  • 32 CPUs
  • 64 GB RAM
  • 1 TB Disk

For production environments, if you deploy stateful applications with the Appcircle Helm chart, you will need significant storage capacity, as specified above. You can configure disk resource allocations through Helm values according to your needs.

However, if you opt to use external services for components such as PostgreSQL or MinIO, the storage requirements for the cluster are significantly reduced to around 50GB. It is highly recommended to deploy stateful apps outside of the Appcircle Helm chart configuration.

tip

For stateful apps that should deployed out of scope this helm chart, you can check the Production Readiness document.

For storage details, you can check the Storage Class Configuration section.

info

Using SSD storage is highly recommended if stateful applications are installed within the Appcircle Helm chart scope. SSDs provide faster read/write speeds, improving the performance and responsiveness of your applications.

Additionally, ensure that your Kubernetes version is 1.29.1 or later to maintain compatibility and support.

4. kubectl​

The kubectl CLI is required.

5. Helm v3​

Helm version 3.11.0 or later is required.

Pre-installation Steps​

1. Ingress Controller​

The Kubernetes cluster should have an Ingress controller installed and configured since Appcircle exposes its services through Ingress objects.

For trial purposes, you can use the default Ingress-Nginx controller deployed within the Helm chart scope.

For production environments, it's recommended to use your own Ingress controller.

Appcircle server supports Ingress-Nginx controller by default. To install Ingress-Nginx controller to the Kubernetes cluster, please check the Ingress-Nginx controller documentation.

info

Other Ingress controllers like HAProxy Ingress controller are also supported by modifying Helm values accordingly.

Enable SSL Passthrough​

You can skip this section if you use the default Ingress-Nginx controller deployed within the Helm chart scope.

Enable ssl-passthrough feature on your ingress-controller Enabling the SSL passthrough depends on the Ingress controller that is used in the Kubernetes cluster. For example:

info

Enabling the SSL passthrough option does not automatically allow all SSL traffic from all Ingress objects to pass through to the original service. Instead, it enables Ingress resources to leverage the SSL passthrough feature, allowing encrypted traffic to reach the backend service without being decrypted by the Ingress controller.

2. Production Readiness​

If you are deploying the Appcircle server for a production environment, it is recommended that stateful applications, such as databases or object storage, be deployed outside the scope of the Appcircle server Helm chart.

For more information, you can check the Production Readiness documentation.

3. Create Namespace​

Create a namespace for the Appcircle server deployment. In this documentation, we will use appcircle as the example namespace.

kubectl create namespace appcircle

4. Create Container Registry Secret​

By default, Appcircle uses its own image registry, which requires authentication with the cred.json file provided by Appcircle.

If you are using your own container image registry to access Appcircle container images, you can either skip authentication if your registry doesn't require it or create a secret for your custom registry.

Follow the steps below to create the registry secret in the appcircle namespace for pods to successfully pull images:

info

If you are using your own container registry, follow the Custom Registry section below.

If your registry doesn't require authentication, you can skip this section.

  • Save the cred.json file.

  • Create the container registry secret:

kubectl create secret docker-registry containerregistry \
  -n appcircle \
  --docker-server='europe-west1-docker.pkg.dev' \
  --docker-username='_json_key' \
  --docker-password="$(cat cred.json)"

Installation​

1. Create values.yaml​

Below is a minimal values.yaml file that you should configure for your deployment.

Please adjust these values according to your environment requirements and save your file.

In the example values below, we used spacetech as an example organization name. You should replace it with your actual organization name or any other value you prefer.

caution

Please review the comments for the values.yaml below. If the values provided are incompatible, the installation may not complete successfully. Ensure that all configurations are correctly entered to avoid potential issues during the setup process.

Click to view example values.yaml file.
# Global configurations for Appcircle deployment
global:
  urls:
    # Main domain configuration - All Appcircle services will be subdomains of this domain
    domainName: .appcircle.spacetech.com
  # SMTP server configuration for sending emails (Authentication, Notifications, Testing Distribution)
  mail:
    smtp:
      # SMTP server host
      host: "smtp.spacetech.com"
      # SMTP Server port, 587 typically used for StartTLS
      port: "587"
      # Email address that will be used as sender
      from: "appcircle@yandex.com"
      # SSL configuration - Set to 'true' if the SMTP server uses SSL/TLS protocol for secure communication, typically on port 465.
      ssl: "false"
      # StartTLS configuration - Set to 'true' if the SMTP server uses StartTLS protocol, typically on port 587.
      tls: "true"
      # SMTP authentication settings
      auth: "true"
      username: "appcircle-smtp-user"
      password: "superSecretSmtpPassword"

# Authentication configuration
auth:
  auth-keycloak:
    # Initial admin user email for Appcircle server
    initialUsername: "admin@spacetech.com"

2. Remove Sensitive Information From values.yaml​

Remove sensitive information such as Appcircle initial user password, SMTP password, SSL certificates, and other secrets from the values.yaml for production environments, by checking the Sensitive Values documentation.

3. Add the Appcircle Helm Repository​

Add the Appcircle Helm repository to the configuration of Helm:

helm repo add appcircle https://helm-package.appcircle.io && \
helm repo update

4. Install the Appcircle Server​

Run the following Helm command to install the Appcircle server chart.

In this example, we deploy the Appcircle server to a single namespace, using appcircle as the namespace and appcircle-server as the Helm release name.

helm install appcircle-server appcircle/appcircle \
  --timeout 1200s \
  -n appcircle \
  -f values.yaml
warning

If you need or want to change the release name, please note that it should be 18 characters or fewer.

You can watch the Appcircle server installation with any Kubernetes monitoring tool. The installation process duration depends on factors such as network speed and the processing power of your Kubernetes nodes. Typically, the installation may take up to 10 to 15 minutes.

To make sure that the Appcircle server is installed successfully, you can run the command below and wait to finish:

kubectl wait --for=condition=ready pod \
  -l app.kubernetes.io/instance=appcircle-server \
  -n appcircle --timeout 1200s && \
  echo "Appcircle is ready to use. Happy building! "

Post-installation Steps​

1. Add DNS Records​

List the Ingresses with kubectl to check the IP address of the Appcircle services domains.

kubectl get ingresses -n appcircle

According to the example output below, you need to configure your DNS as follows:

NAME                               CLASS   HOSTS                                                          ADDRESS        PORTS      AGE
appcircle-apigateway               nginx   api.appcircle.spacetech.com,auth.appcircle.spacetech.com       10.45.140.78   80,443     24m
appcircle-distribution-testerweb   nginx   dist.appcircle.spacetech.com                                   10.45.140.78   80,443     24m
appcircle-resource                 nginx   resource.appcircle.spacetech.com                               10.45.140.78   80,443     24m
appcircle-store-web                nginx   *.store.appcircle.spacetech.com                                10.45.140.78   80,443     24m
appcircle-web-app                  nginx   my.appcircle.spacetech.com                                     10.45.140.78   80,443     24m
appcircle-web-event                nginx   hook.appcircle.spacetech.com                                   10.45.140.78   80,443     24m
appcircle-webeventredis            nginx   kvs.appcircle.spacetech.com                                  10.45.140.78   80,443     24m

  1. Create an A Record for the api domain:

    • api.appcircle.spacetech.com → 10.45.140.78

  2. Create CNAME Records for the other domains:

    • auth.appcircle.spacetech.com → api.appcircle.spacetech.com
    • dist.appcircle.spacetech.com → api.appcircle.spacetech.com
    • resource.appcircle.spacetech.com → api.appcircle.spacetech.com
    • *.store.appcircle.spacetech.com → You can skip this domain and use a Custom Enterprise App Store Domain.
    • my.appcircle.spacetech.com → api.appcircle.spacetech.com
    • hook.appcircle.spacetech.com → api.appcircle.spacetech.com
    • kvs.appcircle.spacetech.com → api.appcircle.spacetech.com

2. Login to the Appcircle Dashboard​

Check the output of the Helm install command to see login URL, initial username and command to get initial user password.

Self-Hosted Configuration:

- Initial Organization Id : 8c23e250-4aa8-4ef6-888b-9514695aa1c7
- Initial User            : admin@spacetech.com
- Retrieve the initial user password by executing the following command:↴
    
    kubectl get secret -n appcircle appcircle-server-auth-keycloak-passwords -ojsonpath='{.data.initialPassword}' | base64 --decode ; echo

You can access the application dashboard at:↴

   https://my.appcircle.spacetech.com


Support:
For any issues or questions, please contact the system administrator or check the application documentation.

3. Apply the Appcircle License​

When you deploy the Appcircle server using Helm, a default license is provided. You can explore the Appcircle with the default license.

To obtain the license you purchased, please share the initial organization ID, which is printed after the helm deployment command, with the Appcircle team and follow the detailed instructions available in the Appcircle License Update section.

Need help?​

Get help from Appcircle's support team, or see how others are using Appcircle by joining our Slack Channel.

Slack
No description available
join.slack.com
Preview of Slack