App Troubleshooting & Post-Deployment Management

App Troubleshooting & Post-Deployment Management

Deploying an app is just the beginning. Managing deployed applications — monitoring status, diagnosing issues, updating specifications, and handling failures — is critical for maintaining a reliable service. This guide covers the complete lifecycle after deployment: troubleshooting common problems, updating running apps, and managing ownership.

Deployment Stages

After submitting an app spec, your deployment progresses through these stages:

Common Deployment Failures

1. 1

   Image not found / pull error

   The Docker image doesn't exist or is private without enterprise mode. Verify the repotag exactly matches your Docker Hub repository (case-sensitive). Ensure the image is set to "public" on Docker Hub.

2. 2

   Container crashes immediately (CrashLoopBackOff)

   The application inside the container is crashing on startup. Common causes: missing environment variables, wrong CMD/entrypoint, application error. Test your image locally with: docker run -e KEY=VALUE yourusername/image:tag

3. 3

   Port conflict

   The containerPorts don't match what your application actually listens on. Verify your application binds to 0.0.0.0 (not localhost/127.0.0.1) on the expected port.

4. 4

   Insufficient resources

   No nodes have enough available resources for your spec. Try reducing cpu, ram, or hdd values, or reduce the number of instances.

5. 5

   App stuck in Pending

   Network may be congested or your resource requirements exceed what's available. Wait 10-15 minutes. If still pending, try adjusting resources down or deploying at off-peak hours.

6. 6

   Health check failures

   Your app starts but doesn't respond on the expected port in time. Add a /health endpoint and ensure the app is ready to serve requests within 60 seconds of startup.

Domain Troubleshooting

• •CNAME not resolving: DNS propagation can take up to 48 hours. Use dig or nslookup to check propagation. CloudFlare changes are typically faster (minutes).
• •SSL certificate errors: Flux uses Let's Encrypt for automatic SSL. If the certificate hasn't provisioned yet, wait 10-15 minutes. Ensure your CNAME points to the correct Flux domain.
• •Wrong domain routing: Verify the domains array in your spec exactly matches your CNAME target. Domains are case-sensitive.
• •Mixed content warnings: If your app serves HTTP content on an HTTPS page. Ensure all internal URLs use relative paths or HTTPS.

Database Connection Issues

• •Connection refused: Verify the database component name matches the hostname in your connection string. Use the component name (from the spec), not localhost or an IP.
• •Authentication failed: Check that environment variables for database credentials match between the database and application components.
• •Timeout: Ensure the database component has started before the application tries to connect. Add retry logic to your app's database connection code.
• •Data not persisting: Verify containerData is configured correctly and points to the directory where the database stores its data files.

Updating a Deployed App

After deploying, you can modify any aspect of your app specification without redeploying from scratch:

• •Update Docker image: Push a new version to Docker Hub, then update the repotag in your spec. Flux nodes pull the new image.
• •Change resources: Adjust cpu, ram, hdd values. The app may be migrated to nodes that match the new requirements.
• •Modify environment variables: Update environmentParameters to change configuration, rotate secrets, or adjust settings.
• •Add/change domains: Update the domains array to point to new custom domains.
• •Change ports: Modify ports and containerPorts as needed.
• •Transfer ownership: Change the owner field to transfer the app to a different Zel ID.

To update: navigate to home.runonflux.io > Applications > Management, find your app, and submit an updated specification. The update is broadcast to the network and applied within minutes.

Monitoring Deployed Apps

• •FluxOS UI: Access any node running your app at http://NODE_IP:16126 to see your app status, resource usage, and logs
• •Flux Explorer: Search for your app on home.runonflux.io to see all instances, their locations, and status
• •FluxOS API: Query http://NODE_IP:16127/apps/installedapps for programmatic monitoring
• •External monitoring: Use UptimeRobot or similar tools to monitor your app's public endpoints

Stopping & Removing an App

To remove a deployed app, navigate to home.runonflux.io > Applications > Management, find your app, and select Remove Application. This stops all instances across the network and frees the resources. Note that all data in containerData volumes is permanently deleted when an app is removed.