docs: add production deployment guide#9
Conversation
Covers Docker Compose and Kubernetes deployment, TLS configuration, database backup/recovery, and automated backup CronJob. Closes #4 Signed-off-by: Mohit Nagaraj <mohitnagaraj20@gmail.com>
Summary of ChangesHello, I'm Gemini Code Assist1! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed! This pull request significantly enhances the project's documentation by introducing a detailed production deployment guide. It provides users with clear, step-by-step instructions for deploying KubeOrch using either Docker Compose for smaller teams or Kubernetes for more robust setups, alongside crucial information on securing deployments with TLS/HTTPS and ensuring data integrity through backup and recovery procedures. This addition aims to streamline the process of moving KubeOrch into a production environment, making it more accessible and reliable for users. Highlights
Using Gemini Code AssistThe full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips. Invoking Gemini You can request assistance from Gemini at any point by creating a comment using either
Customization To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a Limitations & Feedback Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for GitHub and other Google products, sign up here. Footnotes
|
![gemini-code-assist[bot]](https://avatars.githubusercontent.com/in/956858?s=60&v=4){kind=small}
There was a problem hiding this comment.
Code Review
This pull request adds a comprehensive production deployment guide, which is a great addition. However, the guide in its current form has several critical issues that would prevent a user from successfully deploying the application. My review includes feedback on insecure practices, configuration mismatches, and missing resource definitions. Specifically, I've pointed out the problematic use of :latest image tags, insecure Kubernetes secret creation methods, an Ingress path that doesn't match the application's configuration, and missing resource definitions for an Nginx configuration and a PersistentVolumeClaim for backups. Addressing these points will significantly improve the quality and reliability of the guide.
| # docker-compose.production.yml | ||
| services: | ||
| core: | ||
| image: ghcr.io/kubeorch/core:latest |
There was a problem hiding this comment.
Using the :latest image tag in production is generally discouraged as it can lead to unpredictable behavior and makes deployments non-reproducible. If the latest tag is updated with a new, potentially breaking change, your deployment could fail unexpectedly. It also makes it difficult to track which version is running or to perform a rollback.
This comment also applies to the ui image on line 58, and the Kubernetes manifests on lines 186 and 255.
| image: ghcr.io/kubeorch/core:latest | |
| image: ghcr.io/kubeorch/core:v1.0.0 # Or any specific version |
| kubectl create secret generic kubeorch-secrets \ | ||
| --namespace kubeorch \ | ||
| --from-literal=jwt-secret=$(openssl rand -hex 32) \ | ||
| --from-literal=encryption-key=$(openssl rand -hex 16) \ | ||
| --from-literal=mongo-uri=mongodb://mongo:27017/kubeorch |
There was a problem hiding this comment.
Creating secrets with --from-literal=key=$(command) is insecure because the secret value can be exposed in your shell history and process list. For production documentation, it's crucial to demonstrate secure practices.
| kubectl create secret generic kubeorch-secrets \ | |
| --namespace kubeorch \ | |
| --from-literal=jwt-secret=$(openssl rand -hex 32) \ | |
| --from-literal=encryption-key=$(openssl rand -hex 16) \ | |
| --from-literal=mongo-uri=mongodb://mongo:27017/kubeorch | |
| # Create secrets from files for better security | |
| echo -n "$(openssl rand -hex 32)" > jwt.txt | |
| echo -n "$(openssl rand -hex 16)" > enc.txt | |
| kubectl create secret generic kubeorch-secrets \ | |
| --namespace kubeorch \ | |
| --from-file=jwt-secret=./jwt.txt \ | |
| --from-file=encryption-key=./enc.txt \ | |
| --from-literal=mongo-uri=mongodb://mongo:27017/kubeorch | |
| # Clean up the temporary files | |
| rm jwt.txt enc.txt |
| - path: /v1 | ||
| pathType: Prefix | ||
| backend: | ||
| service: | ||
| name: core | ||
| port: | ||
| number: 8080 |
There was a problem hiding this comment.
There's a critical mismatch between the Ingress path and the UI's API endpoint configuration. The Ingress is configured to route /v1 to the core service, but the UI deployment (line 260) is configured with NEXT_PUBLIC_API_URL pointing to .../api. This will cause all API calls from the frontend to fail with a 404 error. The path should be consistent.
| - path: /v1 | |
| pathType: Prefix | |
| backend: | |
| service: | |
| name: core | |
| port: | |
| number: 8080 | |
| - path: /api | |
| pathType: Prefix | |
| backend: | |
| service: | |
| name: core | |
| port: | |
| number: 8080 |
| persistentVolumeClaim: | ||
| claimName: backup-pvc |
There was a problem hiding this comment.
The CronJob for automated backups will fail because it references a PersistentVolumeClaim named backup-pvc that is never created in this guide. The backup pods will be stuck in a Pending state waiting for the PVC, which does not exist. You should include instructions and a manifest for creating this PVC before the CronJob is applied. For example:
# backup-pvc.yaml
apiVersion: v1
kind: PersistentVolumeClaim
metadata:
name: backup-pvc
namespace: kubeorch
spec:
accessModes:
- ReadWriteOnce
resources:
requests:
storage: 5Gi # Adjust size as needed| environment: | ||
| - NEXT_PUBLIC_API_URL=https://your-domain.com/api |
There was a problem hiding this comment.
The ui service configuration is inconsistent with the instructions. The guide has the user define NEXT_PUBLIC_API_URL in the .env file, but the ui service doesn't use this file. Instead, it has a hardcoded environment variable. This can lead to confusion, as changes to the .env file won't be picked up by the UI service. It should use env_file like the core service.
| environment: | |
| - NEXT_PUBLIC_API_URL=https://your-domain.com/api | |
| env_file: .env |
| Add an nginx service to your compose file: | ||
|
|
||
| ```yaml | ||
| nginx: | ||
| image: nginx:alpine | ||
| ports: | ||
| - "80:80" | ||
| - "443:443" | ||
| volumes: | ||
| - ./nginx.conf:/etc/nginx/nginx.conf:ro | ||
| - ./certs:/etc/nginx/certs:ro | ||
| depends_on: | ||
| - core | ||
| - ui | ||
| ``` |
There was a problem hiding this comment.
This section provides a Docker Compose service definition for an Nginx reverse proxy but omits the corresponding nginx.conf file. Without a sample configuration, this part of the guide is incomplete and not actionable for the user, who would have to guess how to route traffic to the core and ui services.
1 participant
Summary
Related Issue
Closes #4
Test plan