feat: improve private git submodules docs

docs/applications/index.md

@@ -146,6 +146,120 @@ You can manually deploy a Pull Request to a unique URL by clicking on the `Deplo
 
 If you are using git submodules, you can set this to `true`. `Enabled by default`.
 
+#### Working with Private Git Submodules
+
+When deploying applications with private Git submodules, you may encounter authentication failures during the clone process. This section explains how to properly configure your repository to work with Coolify.
+
+##### Common Issues
+
+You might see errors like:
+
+```
+fatal: could not read Username for 'https://github.com': No such device or address
+fatal: clone of 'https://github.com/org/submodule.git' into submodule path failed
+```
+
+or
+
+```
+git@github.com: Permission denied (publickey).
+fatal: Could not read from remote repository.
+```
+
+These errors occur because Coolify uses SSH protocol for Git operations, which requires proper authentication configuration for submodules.
+
+##### Prerequisites
+
+Before configuring submodules, ensure:
+
+- Your GitHub App has access permissions to both the main repository AND all submodule repositories
+- The "Submodules" checkbox in Advanced settings is enabled (it should be enabled by default)
+
+##### Solution 1: Use Relative Paths (Recommended)
+
+The most reliable solution is to use relative paths instead of absolute URLs in your `.gitmodules` file. This approach works because Coolify uses SSH protocol for authentication, and relative paths inherit the authentication from the parent repository.
+
+**Before:**
+```ini
+[submodule "prisma"]
+    path = prisma
+    url = https://github.com/organization/prisma.git
+```
+
+**After:**
+```ini
+[submodule "prisma"]
+    path = prisma
+    url = ../prisma.git
+```
+
+::: success Important Notes
+- All submodules must be from the same GitHub organization or user when using relative paths
+- Keep the "Submodules" checkbox enabled in Advanced settings
+- This solution works for both GitHub App and Deploy Key authentication methods
+:::
+
+##### Solution 2: SSH Key Configuration
+
+If relative paths don't work for your use case, you can manually configure SSH keys:
+
+1. Navigate to your Coolify server settings
+2. Add the server's SSH key to your GitHub account's SSH keys (not just the repository's deploy keys)
+3. Ensure the GitHub App has content access to all submodule repositories in your organization settings
+
+##### Solution 3: Alternative Workaround
+
+Some users have reported success with an alternative approach, though this is counter-intuitive:
+
+1. Go to your application's Advanced settings
+2. Uncheck the "Submodules" option
+
+::: warning Note
+This workaround has mixed results and may not work for all configurations. It's recommended to try Solution 1 first.
+:::
+
+##### Troubleshooting
+
+If you're still experiencing issues:
+
+1. **Verify GitHub App Permissions:**
+   - Go to your GitHub organization settings
+   - Navigate to GitHub Apps → Coolify
+   - Ensure the app has access to all repositories including submodules
+
+2. **Check Submodule URLs:**
+   - Run `git submodule status` in your repository
+   - Verify all submodule URLs are using relative paths
+   - Ensure submodules are from the same organization
+
+3. **Test Locally:**
+   - Clone your repository with submodules locally: `git clone --recurse-submodules <your-repo>`
+   - If it fails locally with relative paths, the issue is with your `.gitmodules` configuration
+
+4. **Review Deployment Logs:**
+   - Check the Coolify deployment logs for specific error messages
+   - Look for authentication or permission-related errors
+
+##### Example Configuration
+
+Here's a complete example of a properly configured `.gitmodules` file for an organization with multiple submodules:
+
+```ini
+[submodule "backend"]
+    path = backend
+    url = ../backend.git
+[submodule "shared-components"]
+    path = packages/shared
+    url = ../shared-components.git
+[submodule "config"]
+    path = config
+    url = ../config.git
+```
+
+::: tip Pro Tip
+After updating your `.gitmodules` file, commit and push the changes to your repository. Coolify will use the updated configuration on the next deployment.
+:::
+
 ### Git LFS
 
 If you are using git lfs, you can set this to `true`. `Enabled by default`.
@@ -200,4 +314,4 @@ For detailed guides on each build pack, see the [Build Packs section](/applicati
 
 :::tip Quick Start
 Coolify uses [Nixpacks](https://nixpacks.com) by default, which automatically detects your application type and builds it accordingly. For most applications, you won't need to configure anything.
-:::
+:::