From 6c8fd1950e3d6d698df84a9d81a5d1c4d52f457e Mon Sep 17 00:00:00 2001 From: hiilhan <174327812+hiilhan@users.noreply.github.com> Date: Mon, 14 Jul 2025 09:27:21 +0300 Subject: [PATCH 1/2] sso, eas, podman, self-hosted docs updates --- docs/enterprise-app-store/portal-settings.md | 3 + .../_custom-auth-domain-sso-caution.mdx | 3 + .../_custom-eas-domain-sso-caution.mdx | 3 + .../_custom-td-domain-sso-caution.mdx | 3 + .../configuration/advanced-configuration.md | 3 + .../advanced-configuration/store-dist-dmz.md | 3 + .../ssl-configuration.md | 5 + .../linux-package/installation/docker.md | 45 ++++---- .../linux-package/installation/podman.md | 104 +++++++++++------- 9 files changed, 113 insertions(+), 59 deletions(-) create mode 100644 docs/self-hosted-appcircle/install-server/_custom-auth-domain-sso-caution.mdx create mode 100644 docs/self-hosted-appcircle/install-server/_custom-eas-domain-sso-caution.mdx create mode 100644 docs/self-hosted-appcircle/install-server/_custom-td-domain-sso-caution.mdx diff --git a/docs/enterprise-app-store/portal-settings.md b/docs/enterprise-app-store/portal-settings.md index 35c3c5a45..6a281525b 100644 --- a/docs/enterprise-app-store/portal-settings.md +++ b/docs/enterprise-app-store/portal-settings.md @@ -7,6 +7,7 @@ sidebar_position: 3 import Screenshot from '@site/src/components/Screenshot'; import ContentRef from '@site/src/components/ContentRef'; +import CustomEasSsoCaution from '@site/docs/self-hosted-appcircle/install-server/\_custom-td-domain-sso-caution.mdx'; Portal settings allow you to configure your authentication and domain settings. @@ -205,6 +206,8 @@ After creating the DNS settings, type your custom domain name, select your certi + + :::caution If you are working on a sub organization, you will not have access to Customize and Settings sections on Enterprise App Store module. diff --git a/docs/self-hosted-appcircle/install-server/_custom-auth-domain-sso-caution.mdx b/docs/self-hosted-appcircle/install-server/_custom-auth-domain-sso-caution.mdx new file mode 100644 index 000000000..65b9ae058 --- /dev/null +++ b/docs/self-hosted-appcircle/install-server/_custom-auth-domain-sso-caution.mdx @@ -0,0 +1,3 @@ +:::caution +If you are already using **Single Sign-On (SSO)** and enable the **DMZ custom auth domain**, you should delete your existing SSO configurations and recreate them with the same settings on the Appcircle dashboard. +::: \ No newline at end of file diff --git a/docs/self-hosted-appcircle/install-server/_custom-eas-domain-sso-caution.mdx b/docs/self-hosted-appcircle/install-server/_custom-eas-domain-sso-caution.mdx new file mode 100644 index 000000000..d12b5d676 --- /dev/null +++ b/docs/self-hosted-appcircle/install-server/_custom-eas-domain-sso-caution.mdx @@ -0,0 +1,3 @@ +:::caution +If you have configured **SSO authentication** for the Enterprise App Store and enable the **custom domain**, you should delete your existing Enterprise App Store SSO configuration and recreate it with the same settings on the Appcircle dashboard. +::: \ No newline at end of file diff --git a/docs/self-hosted-appcircle/install-server/_custom-td-domain-sso-caution.mdx b/docs/self-hosted-appcircle/install-server/_custom-td-domain-sso-caution.mdx new file mode 100644 index 000000000..3bb8e249a --- /dev/null +++ b/docs/self-hosted-appcircle/install-server/_custom-td-domain-sso-caution.mdx @@ -0,0 +1,3 @@ +:::caution +If you have configured **SSO authentication** for Testing Distribution and enable the **custom domain**, you should delete your existing Testing Distribution SSO configuration and recreate it with the same settings on the Appcircle dashboard. +::: \ No newline at end of file diff --git a/docs/self-hosted-appcircle/install-server/helm-chart/configuration/advanced-configuration.md b/docs/self-hosted-appcircle/install-server/helm-chart/configuration/advanced-configuration.md index 5630a37cb..450736f76 100644 --- a/docs/self-hosted-appcircle/install-server/helm-chart/configuration/advanced-configuration.md +++ b/docs/self-hosted-appcircle/install-server/helm-chart/configuration/advanced-configuration.md @@ -8,6 +8,7 @@ sidebar_label: Advanced Configuration import NeedHelp from '@site/docs/\_need-help.mdx'; import ApplyHelmConfigurationChanges from '@site/docs/self-hosted-appcircle/install-server/helm-chart/configuration/\_apply-helm-configuration-changes.mdx'; +import CustomTdSsoCaution from '@site/docs/self-hosted-appcircle/install-server/\_custom-td-domain-sso-caution.mdx'; For advanced configuration options, open the `values.yaml` file with your preferred text editor and modify the settings as needed. @@ -38,6 +39,8 @@ distribution: The emails related to the Testing Distribution will now include the new domain in the links. Please note that old links associated with the previous domain will no longer work. ::: + + After updating the `values.yaml` file, create a TLS secret for the custom domain using the following command: :::info diff --git a/docs/self-hosted-appcircle/install-server/linux-package/configure-server/advanced-configuration/store-dist-dmz.md b/docs/self-hosted-appcircle/install-server/linux-package/configure-server/advanced-configuration/store-dist-dmz.md index 5dcbbf7d6..a3872e1e8 100644 --- a/docs/self-hosted-appcircle/install-server/linux-package/configure-server/advanced-configuration/store-dist-dmz.md +++ b/docs/self-hosted-appcircle/install-server/linux-package/configure-server/advanced-configuration/store-dist-dmz.md @@ -24,6 +24,7 @@ import FirewalldConfiguration from '@site/docs/self-hosted-appcircle/install-ser import UFWConfiguration from '@site/docs/self-hosted-appcircle/install-server/linux-package/configure-server/\_ufw-configuration.mdx'; import SwapConfiguration from '@site/docs/self-hosted-appcircle/install-server/linux-package/configure-server/\_swap-configuration.mdx'; import DowntimeCaution from '@site/docs/self-hosted-appcircle/install-server/linux-package/configure-server/\_appcircle-server-downtime-caution.mdx'; +import CustomAuthSSOCaution from '@site/docs/self-hosted-appcircle/install-server/\_custom-auth-domain-sso-caution.mdx'; import Screenshot from '@site/src/components/Screenshot'; ## Overview @@ -856,6 +857,8 @@ If you enable the **DMZ custom domain** and configure **Single Sign-On (SSO)**, Without this update, authentication requests from the DMZ domain will be blocked, causing SSO login failures due to unrecognized redirect URIs. ::: + + - **[Upgrade](#upgrading-appcircle-dmz-and-appcircle-server)** the Appcircle server and DMZ server for changes to be applied. import NeedHelp from '@site/docs/\_need-help.mdx'; diff --git a/docs/self-hosted-appcircle/install-server/linux-package/configure-server/integrations-and-access/ssl-configuration.md b/docs/self-hosted-appcircle/install-server/linux-package/configure-server/integrations-and-access/ssl-configuration.md index c3275e0cd..b2b4215fb 100644 --- a/docs/self-hosted-appcircle/install-server/linux-package/configure-server/integrations-and-access/ssl-configuration.md +++ b/docs/self-hosted-appcircle/install-server/linux-package/configure-server/integrations-and-access/ssl-configuration.md @@ -8,6 +8,7 @@ sidebar_position: 3 import RestartAppcircleServer from '@site/docs/self-hosted-appcircle/install-server/linux-package/configure-server/\_restart-appcircle-server.mdx'; import SpacetechExampleInfo from '@site/docs/self-hosted-appcircle/install-server/linux-package/configure-server/\_spacetech-example-info.mdx'; import DowntimeCaution from '@site/docs/self-hosted-appcircle/install-server/linux-package/configure-server/\_appcircle-server-downtime-caution.mdx'; +import CustomEasSsoCaution from '@site/docs/self-hosted-appcircle/install-server/\_custom-eas-domain-sso-caution.mdx';import CustomTdSsoCaution from '@site/docs/self-hosted-appcircle/install-server/\_custom-td-domain-sso-caution.mdx'; import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem'; @@ -361,6 +362,8 @@ For this reason, you can only use `store.appcircle.spacetech.com` for all your n It's possible to use a custom domain for the Enterprise App Store. In this case we need to make extra configuration for our custom domain. + + Most likely, our custom domain won't be covered by main domain certificate. So we may need to create new public certificate and private key pair for the custom domain. Custom domain HTTPS settings are similar to main domain conceptually. After enabling HTTPS for main domain, it won't be hard to enable HTTPS for Enterprise App Store custom domain. @@ -502,6 +505,8 @@ It's possible to use a custom domain for the Testing Distribution. In this case, Please be aware that, after you change the Testing Distribution domain or the SSL settings, the links in the **emails that were sent to the testers with the previous domain and previous SSL settings will be invalid.** ::: + + Most likely, our custom domain won't be covered by the main domain certificate. In this case, we need to create a new public certificate and private key pair for the custom domain. Custom domain HTTPS settings are similar to the main domain configuration conceptually. After enabling HTTPS for the main domain, it won't be hard to enable HTTPS for the Testing Distribution custom domain. diff --git a/docs/self-hosted-appcircle/install-server/linux-package/installation/docker.md b/docs/self-hosted-appcircle/install-server/linux-package/installation/docker.md index e92ade754..8d141ba5c 100644 --- a/docs/self-hosted-appcircle/install-server/linux-package/installation/docker.md +++ b/docs/self-hosted-appcircle/install-server/linux-package/installation/docker.md @@ -429,27 +429,6 @@ We have `user-secret` filled in successfully and don't need `projects/spacetech/ rm projects/spacetech/secret.yaml ``` -:::caution - -On your first export, which makes `global.yaml` template for you, also creates an empty template file for `user-secret` as seen below: - -```bash -base64 -d projects/spacetech/user-secret -``` - -```yaml -smtpServer: - password: -keycloak: - initialPassword: -``` - -If you prefer defining above variables in `global.yaml`, then they should not be in `user-secret`. - -If you defined all of them in `global.yaml`,simply remove `user-secret` before next steps. - -::: - Note that after changes made to yaml files, you must execute the script again for the changes to take effect as shown below. ```bash @@ -467,6 +446,7 @@ Appcircle server has some subdomains for different services. So, you need to add - my - resource - store +- *.store - monitor - redis - (optional) Enterprise App Store's Custom Domain @@ -479,7 +459,19 @@ If your configuration (`global.yaml`) has setting `storeWeb.customDomain.enabled Below is an example DNS configuration that is compatible with our sample scenario. - +1. **Create an A Record for the `my` subdomain:** + - `my.appcircle.spacetech.com` → **198.244.212.84** + +2. **Create CNAME Records for the other subdomains:** + - `api.appcircle.spacetech.com` → **my.appcircle.spacetech.com** + - `auth.appcircle.spacetech.com` → **my.appcircle.spacetech.com** + - `dist.appcircle.spacetech.com` → **my.appcircle.spacetech.com** + - `hook.appcircle.spacetech.com` → **my.appcircle.spacetech.com** + - `monitor.appcircle.spacetech.com` → **my.appcircle.spacetech.com** + - `redis.appcircle.spacetech.com` → **my.appcircle.spacetech.com** + - `resource.appcircle.spacetech.com` → **my.appcircle.spacetech.com** + - `*.store.appcircle.spacetech.com` → **my.appcircle.spacetech.com** + You can skip this subdomain and use a [Custom Enterprise App Store Domain](https://docs.appcircle.io/enterprise-app-store/portal-settings#store-domain). If you have a dedicated DNS, adding subdomains will be enough to run self-hosted Appcircle server in an easy and quick way. @@ -525,6 +517,10 @@ On self-hosted Appcircle server, you should add below entries to the `/etc/hosts 0.0.0.0 store.spacetech.com ``` +:::note +`*.store` subdomain is not required for the server side. That is why it is not included in the list above. +::: + For clients that will connect to self-hosted Appcircle server, either self-hosted runners or end-users using their browsers for web UI, should add external IP of the server to their `/etc/hosts` files. External IP is the address of self-hosted Appcircle server that other hosts in the network can reach to server using that address. You can get external IP of self-hosted Appcircle server with below command. @@ -545,11 +541,16 @@ Other clients that connect to the server should add below entries to their `/etc 35.241.181.2 my.appcircle.spacetech.com 35.241.181.2 resource.appcircle.spacetech.com 35.241.181.2 store.appcircle.spacetech.com +35.241.181.2 .store.appcircle.spacetech.com 35.241.181.2 monitor.appcircle.spacetech.com 35.241.181.2 redis.appcircle.spacetech.com 35.241.181.2 store.spacetech.com ``` +:::caution +Wildcard subdomains are not supported in the `/etc/hosts` file. Therefore, the `*.store.appcircle.spacetech.com` domain cannot be defined in the hosts file. As a temporary solution for testing, you can get your store prefix from the Appcircle dashboard at `Enterprise App Store > Settings > Store Domain`. Then, replace `` with your store prefix in the example above. The result would look like this: `biu3oeaktp7l.store.appcircle.spacetech.com`. This is a temporary solution for testing until you set up proper DNS for your self-hosted Appcircle server. +::: + With this network setup, you can run and test both self-hosted Appcircle server and connected self-hosted runners with all functionality. ### 5. Initialize Vault diff --git a/docs/self-hosted-appcircle/install-server/linux-package/installation/podman.md b/docs/self-hosted-appcircle/install-server/linux-package/installation/podman.md index d8b295fab..be76a083b 100644 --- a/docs/self-hosted-appcircle/install-server/linux-package/installation/podman.md +++ b/docs/self-hosted-appcircle/install-server/linux-package/installation/podman.md @@ -81,6 +81,20 @@ For production environments, **recommended** hardware requirements are The Appcircle server supports Podman as the container runtime. The minimum required version of Podman is 4.3.0 or higher. +:::caution Podman Compose Version Compatibility + +Podman Compose version `1.3.0` contains a known issue affecting relative path handling. To avoid this bug, use version `1.2.0` or earlier, or version `1.4.0` or later. + +::: + +:::info RHEL 8 Python Version Requirement + +Podman Compose version `1.4.0` and later require Python `3.7` or higher. + +RHEL 8 systems may have an older Python version by default. Before installing or upgrading Podman Compose to `1.4.0` or newer, ensure Python `3.7+` is installed and set as the default `python3` interpreter. + +::: + #### Enabling the Linger Option @@ -172,6 +186,30 @@ Older podman versions may be incompatible for our operations. Podman versions ab +:::tip Network Conflicts & Troubleshooting + +**Podman Network Conflicts:** +Podman containers (especially rootless) may use default IP ranges like `10.0.2.100` (see [GitHub Discussion](https://github.com/containers/podman/discussions/10472)). If your host or LAN uses the same subnet, you may experience connectivity issues or unexpected routing behavior. + +**How to Troubleshoot:** +- Use `traceroute` inside a container to check network paths. You can use a toolbox image for this. +- Inspect container IPs with: + ```bash + podman inspect --format '{{ .NetworkSettings.IPAddress }}' + ``` +- If you see conflicts, consider changing Podman's network CIDR with the `--subnet` option (see [Podman Network Docs](https://docs.podman.io/en/v5.5.2/markdown/podman-network-create.1.html#subnet-subnet)). + - First, remove the existing network: + ```bash + podman network rm appcircle-backend + ``` + - Then, create a new network with your custom CIDR: + ```bash + podman network create --subnet 192.168.33.0/24 appcircle-backend + ``` + `appcircle-backend` is the network used by the Appcircle server. Make sure to use this exact name in your command. + +::: + #### Change the Podman Data Location In certain scenarios, you may encounter situations where the available free space on the root directory (`/`) is limited. However, you might have ample free space in a different directory, such as `$HOME` or `/opt`. @@ -433,27 +471,6 @@ We have `user-secret` filled in successfully and don't need `projects/spacetech/ rm projects/spacetech/secret.yaml ``` -:::caution - -On your first export, which makes `global.yaml` template for you, also creates an empty template file for `user-secret` as seen below: - -```bash -base64 -d projects/spacetech/user-secret -``` - -```yaml -smtpServer: - password: -keycloak: - initialPassword: -``` - -If you prefer defining above variables in `global.yaml`, then they should not be in `user-secret`. - -If you defined all of them in `global.yaml`,simply remove `user-secret` before next steps. - -::: - Note that after changes made to yaml files, you must execute the script again for the changes to take effect as shown below. ```bash @@ -471,6 +488,7 @@ Appcircle server has some subdomains for different services. So, you need to add - my - resource - store +- *.store - monitor - redis - (optional) Enterprise App Store's Custom Domain @@ -514,30 +532,42 @@ Entries in the hosts file have the following format: Address HostName ``` -On self-hosted Appcircle server, you should add below entries to the `/etc/hosts` file. +##### Server Side Configuration -```txt -0.0.0.0 api.appcircle.spacetech.com -0.0.0.0 auth.appcircle.spacetech.com -0.0.0.0 dist.appcircle.spacetech.com -0.0.0.0 hook.appcircle.spacetech.com -0.0.0.0 my.appcircle.spacetech.com -0.0.0.0 resource.appcircle.spacetech.com -0.0.0.0 store.appcircle.spacetech.com -0.0.0.0 monitor.appcircle.spacetech.com -0.0.0.0 redis.appcircle.spacetech.com -0.0.0.0 store.spacetech.com -``` +In production environments, it is recommended to configure proper DNS records before installation. -For clients that will connect to self-hosted Appcircle server, either self-hosted runners or end-users using their browsers for web UI, should add external IP of the server to their `/etc/hosts` files. External IP is the address of self-hosted Appcircle server that other hosts in the network can reach to server using that address. +For testing or initial setup, you may temporarily add the necessary subdomains to the server’s `/etc/hosts` file using the server’s external IP address. -You can get external IP of self-hosted Appcircle server with below command. +:::caution +Changes made to the server’s `/etc/hosts` file are propagated into the containers by Podman. +Do not use `0.0.0.0` as the IP address for Appcircle subdomains. Containers interpret `0.0.0.0` as their own external IP, which can break inter-container communication. +::: + +To determine the external IP address of your self-hosted Appcircle server, run: ```bash hostname -I | awk '{print $1}' ``` -Let's assume we got value `35.241.181.2` as an example. +For example, if your server’s external IP is `35.241.181.2`, add the following entries to `/etc/hosts`: +```txt +35.241.181.2 api.appcircle.spacetech.com +35.241.181.2 auth.appcircle.spacetech.com +35.241.181.2 dist.appcircle.spacetech.com +35.241.181.2 hook.appcircle.spacetech.com +35.241.181.2 my.appcircle.spacetech.com +35.241.181.2 resource.appcircle.spacetech.com +35.241.181.2 store.appcircle.spacetech.com +35.241.181.2 monitor.appcircle.spacetech.com +35.241.181.2 redis.appcircle.spacetech.com +35.241.181.2 store.spacetech.com +``` + +##### Client Side Configuration + +For clients that will connect to self-hosted Appcircle server, either self-hosted runners or end-users using their browsers for web UI, should add external IP of the server to their `/etc/hosts` files. External IP is the address of self-hosted Appcircle server that other hosts in the network can reach to server using that address. + +We already have the external IP address of our server as `35.241.181.2` from previous step. Other clients that connect to the server should add below entries to their `/etc/hosts` files. From e1424404349bd2a7fdd77899fb56b2dc26433a35 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Onur=20Y=C4=B1lmaz?= Date: Wed, 10 Dec 2025 14:36:52 +0300 Subject: [PATCH 2/2] Podman requirements section is done in https://github.com/appcircleio/appcircle-docusaurus/pull/1122 --- .../linux-package/installation/podman.md | 14 -------------- 1 file changed, 14 deletions(-) diff --git a/docs/self-hosted-appcircle/install-server/linux-package/installation/podman.md b/docs/self-hosted-appcircle/install-server/linux-package/installation/podman.md index be76a083b..316c682c0 100644 --- a/docs/self-hosted-appcircle/install-server/linux-package/installation/podman.md +++ b/docs/self-hosted-appcircle/install-server/linux-package/installation/podman.md @@ -81,20 +81,6 @@ For production environments, **recommended** hardware requirements are The Appcircle server supports Podman as the container runtime. The minimum required version of Podman is 4.3.0 or higher. -:::caution Podman Compose Version Compatibility - -Podman Compose version `1.3.0` contains a known issue affecting relative path handling. To avoid this bug, use version `1.2.0` or earlier, or version `1.4.0` or later. - -::: - -:::info RHEL 8 Python Version Requirement - -Podman Compose version `1.4.0` and later require Python `3.7` or higher. - -RHEL 8 systems may have an older Python version by default. Before installing or upgrading Podman Compose to `1.4.0` or newer, ensure Python `3.7+` is installed and set as the default `python3` interpreter. - -::: - #### Enabling the Linger Option