#BE-6273 SSO, EAS, Podman, Self-hosted docs updates

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
 
 <Screenshot url="https://cdn.appcircle.io/docs/assets/BE-4867-domain.png" alt="Custom Domain Settings for Enterprise Portal" />
 
+<CustomEasSsoCaution />
+
 :::caution
 
 If you are working on a sub organization, you will not have access to Customize and Settings sections on Enterprise App Store module.

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.
+:::

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.
+:::

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.
+:::

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.
 :::
 
+<CustomTdSsoCaution />
+
 After updating the `values.yaml` file, create a TLS secret for the custom domain using the following command:
 
 :::info

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.
 :::
 
+<CustomAuthSSOCaution />
+
 - **[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';

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.
 
+<CustomEasSsoCaution />
+
 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.**
 :::
 
+<CustomTdSsoCaution />
+
 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.

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.
 
-<Screenshot url='https://cdn.appcircle.io/docs/assets/be-3839-cloudflare-ss.png' />
+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  <your-store-prefix>.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 `<your-store-prefix>` 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

docs/self-hosted-appcircle/install-server/linux-package/installation/podman.md

@@ -172,6 +172,30 @@ Older podman versions may be incompatible for our operations. Podman versions ab
 
 <NetavarkConfiguration/>
 
+:::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 <container_name> --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 +457,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 +474,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 +518,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.