diff --git a/.github/workflows/quality.yml b/.github/workflows/quality.yml index 93964e7..aa7e98b 100644 --- a/.github/workflows/quality.yml +++ b/.github/workflows/quality.yml @@ -33,3 +33,9 @@ jobs: - name: Check code formatting 🎨 run: node --run format:check + + - name: Check types 🧩 + run: node --run types:check + + - name: Check build 🏗️ + run: node --run build diff --git a/content/docs/configuration/env-variables.mdx b/content/docs/configuration/env-variables.mdx index 8f370d0..9ea996d 100644 --- a/content/docs/configuration/env-variables.mdx +++ b/content/docs/configuration/env-variables.mdx @@ -15,17 +15,19 @@ These environment variables can be used in both the agent and the hub. | ----------- | ------------- | --------------------- | ---------------------------------------------------------- | | `DEBUG` | `false` | no | Debug mode | | `LOG_LEVEL` | `info ` | no | Log level. Options: trace, debug, info, warn, error, fatal | +| `LOG_JSON` | `false` | no | Enable JSON formatted logs. | ## Hub -| Variable | Default Value | Recommended to change | Description | -| ------------------ | ------------- | --------------------- | ------------------------------------------------------------------------------------------ | -| `APP_URL` | `-` | yes (required) | The URL of the OrcaCD instance | -| `APP_SECRET` | `-` | yes (required) | Secret used for authentication and encryption. Generate one with `openssl rand -base64 42` | -| `HOST` | `0.0.0.0 ` | no | Host address | -| `PORT` | `8080 ` | no | Container port | -| `DisableLocalAuth` | `false ` | no | Disable password authentication. Useful when using SSO with OIDC | -| `TrustedProxies` | `- ` | no | Recommended if using a reverse proxy. Comma seperated list of network origins | +| Variable | Default Value | Recommended to change | Description | +| -------------------- | ------------- | --------------------- | ------------------------------------------------------------------------------------------------------- | +| `APP_URL` | `-` | yes (required) | The URL of the OrcaCD instance | +| `APP_SECRET` | `-` | yes (required) | Secret used for authentication and encryption. Generate one with `openssl rand -base64 42` | +| `HOST` | `0.0.0.0 ` | no | Host address | +| `PORT` | `8080 ` | no | Container port | +| `DISABLE_LOCAL_AUTH` | `false ` | no | Disable password authentication. Useful when using SSO with OIDC | +| `TRUSTED_PROXIES` | `- ` | no | Recommended if using a reverse proxy. Comma seperated list of network origins | +| `DEMO` | `false ` | no | This mode disables all functions except the login and additionally seeds some demo data in the database | ## Agent diff --git a/content/docs/demo.mdx b/content/docs/demo.mdx new file mode 100644 index 0000000..e3f76d9 --- /dev/null +++ b/content/docs/demo.mdx @@ -0,0 +1,13 @@ +--- +title: Demo +description: Live demo of Orca CD in action, showcasing its features and capabilities. +--- + +To access the live demo of Orca CD, please visit the following link: + +[Live Demo](https://demo.orcacd.com) + +The credentials for the demo are as follows: + +- Username: `demo@orcacd.dev` +- Password: `demo-password` diff --git a/content/docs/guides/oidc.mdx b/content/docs/guides/oidc.mdx index 1c3dbc7..fe9c204 100644 --- a/content/docs/guides/oidc.mdx +++ b/content/docs/guides/oidc.mdx @@ -3,8 +3,45 @@ title: OIDC Authentication description: Learn how to use OIDC providers for auhentication in OrcaCD --- -TODO: +OrcaCD supports OIDC authentication, allowing users to log in using their existing accounts from various OIDC providers. This guide will walk you through the process of setting up OIDC authentication in OrcaCD. + + + When using OIDC authentication, you can disable password login to enhance security. This ensures + that users can only log in using their OIDC provider accounts, reducing the risk of unauthorized + access through weak or compromised passwords. Before disabling password login, make sure the OIDC + authentication is properly configured and tested. + + To disable password login, set the `DISABLE_LOCAL_AUTH` environment variable. Look at the [environment variables documentation](/docs/configuration/env-variables) for more details. + + ## Example (Pocket Id) -TODO +To set up OIDC authentication with Pocket Id, follow these steps: + +### 1. Create a Pocket Id Application + +Go to your Pocket ID dashboard and create a new application. Give it a name and leave the redirect URI blank for now. + +TODO: Pocket Id application creation image here + +### 2. Configure OrcaCD + +1. Go to the OrcaCD Admin settings and navigate to the OIDC configuration section. +2. Create a new OIDC provider configuration with the following details: + - **Name**: A name for your OIDC provider (e.g., "Pocket Id"). + - **Issuer URL**: The issuer URL provided by Pocket Id (e.g., `https://pocketid.com`). + - **Client ID**: The client ID from your Pocket Id application. + - **Client Secret**: The client secret from your Pocket Id application. +3. Save the configuration and ensure it is enabled. + +TODO: Orca CD OIDC configuration image here + +### 3. Test the Configuration + +1. Log out of OrcaCD if you are currently logged in. +2. Click on the "Login with Pocket Id" button on the login page. +3. You will be redirected to the Pocket Id login page. Enter your credentials and log in. +4. After successful authentication, you will be redirected back to OrcaCD and logged in with your Pocket Id account. + +TODO: Login page image here diff --git a/content/docs/guides/reverse-proxy.mdx b/content/docs/guides/reverse-proxy.mdx index dd84496..6be3249 100644 --- a/content/docs/guides/reverse-proxy.mdx +++ b/content/docs/guides/reverse-proxy.mdx @@ -9,4 +9,26 @@ TODO ## Traefik -TODO +To use Traefik as a reverse proxy for OrcaCD, you can add the following labels to your Docker Compose configuration for the OrcaCD Hub service: + +```yml +services: + hub: + image: ghcr.io/orcacd/hub:latest + container_name: orca-hub + ports: + - "127.0.0.1:8080:8080" + restart: unless-stopped + env_file: .env + labels: // [!code ++] + - "traefik.enable=true" // [!code ++] + - "traefik.http.routers.orcacd.rule=Host(`orcacd.example.com`)" // [!code ++] + volumes: + - ./data/hub:/app/data +``` + +Now when registering an agent, you can use following URL as the Hub URL: + +``` +HUB_URL=http://orcacd.example.com +``` diff --git a/content/docs/helping-out/contributing.mdx b/content/docs/helping-out/contributing.mdx index 6d1b041..61ba795 100644 --- a/content/docs/helping-out/contributing.mdx +++ b/content/docs/helping-out/contributing.mdx @@ -3,4 +3,64 @@ title: Contributing description: Learn how to contribute to the OrcaCD project --- -TODO +Any contribution is greatly appreciated. You don't need to be a developer to contribute. You can help by translating the app, reporting issues, or simply sharing your ideas for new features. + +If you have any questions, please do not hesitate to contact us. + +Read our [Code of Conduct](https://github.com/OrcaCD/orca-cd/blob/main/CODE_OF_CONDUCT.md) to keep our community approachable and respectable. + +## Security + +If you would like to report a security vulnerability, please take a look at [SECURITY.md](https://github.com/OrcaCD/orca-cd/blob/main/SECURITY.md) + +## Code contributions + +We welcome code contributions and encourage clear, well-documented changes that include appropriate tests. +When introducing a new feature, please ensure you add relevant tests. +For breaking changes or major new features, open an issue beforehand to discuss your proposal with the team. + +### Required tools + +We use Go and Node.js for the development of the backend and frontend respectively. For a detailed list of required tools and their versions, please refer to the [CONTRIBUTING.md](https://github.com/OrcaCD/orca-cd/blob/main/CONTRIBUTING.md#required-tools) file in the repository. + +### Setting up the development environment + +1. Install all required tools listed above. +2. Clone the repository and navigate to the project directory. +3. For the frontend, navigate to the `frontend/` directory and run `npm ci` to install dependencies. +4. Run the frontend development server with `node --run dev` from the `frontend/` directory. +5. Run the backend services with `just run-hub` and `just run-agent` in the `backend/` directory. +6. Access the app at `http://localhost:3000` and the hub API at `http://localhost:8080`. + +### Running locally with Docker + +A Docker Compose file is provided for running the full stack locally: + +```sh +docker compose -f docker-compose.dev.yaml up --build +``` + +The hub service will be available at `http://localhost:8080`. + +### Submitting a Pull Request + +Before you submit the pull request for review please ensure that + +- The pull request naming follows the [Conventional Commits specification](https://www.conventionalcommits.org): + + `[optional scope]: ` + + example: + + ```yml + fix: hide global audit log switch for non admin users + ``` + + Where `TYPE` can be: + - feat - is a new feature + - doc - documentation only changes + - fix - a bug fix + - refactor - code change that neither fixes a bug nor adds a feature + +- Your pull request has a detailed description +- You have added tests for any new features or bug fixes diff --git a/content/docs/helping-out/documentation.mdx b/content/docs/helping-out/documentation.mdx index 5957a95..4462e3f 100644 --- a/content/docs/helping-out/documentation.mdx +++ b/content/docs/helping-out/documentation.mdx @@ -3,4 +3,36 @@ title: Documentation description: Contribute to improving the OrcaCD website or documentation --- -TODO +This guide explains how to add or edit documentation (Fumadocs). + +## 1. Where docs live + +All markdown pages are under `/content/docs`. The file `meta.json` controls the sidebar structure and order. + +## 2. Adding a new page + +1. Pick the correct folder that matches a collection pattern (e.g. `/guides`). + +2. Create `/content/docs/
/.md`. + +3. Add frontmatter: + +```yaml +--- +title: Installation +description: Get OrcaCD running quickly with Docker installation +--- +``` + +4. Run `npm run dev` and check your page at `http://localhost:3000/docs/
/`. + + + To use components in the documentation please look at the [Fumadadocs Documentation for + Markdown](https://www.fumadocs.dev/docs/markdown) + + +## 3. Submitting changes + +After making changes you can create a pull request to the `main` branch. Please make sure to commit using Conventional Commits (`doc: update guides`). + +Thanks for helping out! diff --git a/content/docs/helping-out/translating.mdx b/content/docs/helping-out/translating.mdx index f469246..5a6aafd 100644 --- a/content/docs/helping-out/translating.mdx +++ b/content/docs/helping-out/translating.mdx @@ -13,17 +13,13 @@ Use informal language for translations 1. Visit our [Crowdin project page](https://crowdin.com/project/orca-cd). 2. Choose the language you wish to translate into. -3. Open the `en-US.json` source file. +3. Open the `en.json` source file. 4. Now you can start translating the strings. ## Adding a New Language -TODO: Add language request issue template here - -Is your language missing from Crowdin? You can [request its addition](https://crowdin.com/project/orca-cd). +Is your language missing from Crowdin? You can [request its addition](https://github.com/OrcaCD/orca-cd/issues/new?assignees=&labels=language-request&projects=&template=language-request.yml&title=%F0%9F%8C%90+Language+request%3A+%3Clanguage+name+in+english%3E). ## Need Help? -TODO: Add localization discussion - -Encountering issues while translating? Join the [Localization discussion](https://crowdin.com/project/orca-cd) to seek help and share experiences. +Encountering issues while translating? Join the [Localization discussion](https://github.com/OrcaCD/orca-cd/discussions/86) to seek help and share experiences. diff --git a/content/docs/index.mdx b/content/docs/index.mdx index fd1a0e0..8e4714b 100644 --- a/content/docs/index.mdx +++ b/content/docs/index.mdx @@ -8,11 +8,17 @@ description: Welcome to OrcaCD - A simple service for using gitops with docker breaking changes at any time. -import { HomeIcon } from "lucide-react"; +OrcaCD is a simple GitOps tool for Docker. It allows you to deploy your applications using Git as the source of truth. With OrcaCD, you can easily manage your Docker containers and keep them in sync with your Git repository. + +TODO: -TODO: About section (motivation, ...) +- Detailed project description +- Master degree project motivation +- Core components and concepts (hub/agent) -TODO: Image examples +TODO: Image examples (application page, agents page, repositories page) + +import { HomeIcon } from "lucide-react"; @@ -23,6 +29,12 @@ TODO: Image examples +## Get to know OrcaCD + +[Try the OrcaCD Demo](/docs/demo) + +TODO: demo image or gif here + ## Useful Links - [Installation](/docs/setup/installation) diff --git a/content/docs/meta.json b/content/docs/meta.json index 5bc7048..cbc86d6 100644 --- a/content/docs/meta.json +++ b/content/docs/meta.json @@ -5,6 +5,7 @@ "pages": [ "---Getting Started---", "index", + "demo", "---[Rocket]Setup---", "...setup", "---[Settings]Configuration---", diff --git a/content/docs/setup/upgrading.mdx b/content/docs/setup/upgrading.mdx index ece3078..66c84d8 100644 --- a/content/docs/setup/upgrading.mdx +++ b/content/docs/setup/upgrading.mdx @@ -7,6 +7,14 @@ description: Keep your OrcaCD installation up to date Before upgrading OrcaCD in production, we strongly recommend creating a backup of your database and keeping a copy of your current `.env` and `docker-compose.yml` files. This gives you a rollback path if something goes wrong. + + To create a backup of your database, you can copy the `hub.db` file from your docker volumes to a safe location. For example: + + ```bash + docker compose down + docker cp orca-hub:/data/hub.db ./hub_backup.db + ``` + For upgrading OrcaCD when using Docker, you just need to pull the latest image and restart the services: diff --git a/public/assets/icons/github.svg b/public/assets/icons/github.svg new file mode 100644 index 0000000..9d89aa8 --- /dev/null +++ b/public/assets/icons/github.svg @@ -0,0 +1 @@ +github [#142] \ No newline at end of file diff --git a/source.config.ts b/source.config.ts index 35808f4..54138e2 100644 --- a/source.config.ts +++ b/source.config.ts @@ -1,3 +1,4 @@ +import { remarkSteps } from "fumadocs-core/mdx-plugins"; import { defineConfig, defineDocs } from "fumadocs-mdx/config"; import lastModified from "fumadocs-mdx/plugins/last-modified"; @@ -12,4 +13,7 @@ export const docs = defineDocs({ export default defineConfig({ plugins: [lastModified()], + mdxOptions: { + remarkPlugins: [remarkSteps], + }, }); diff --git a/src/routes/index.tsx b/src/routes/index.tsx index 2bf0fad..e9e70c9 100644 --- a/src/routes/index.tsx +++ b/src/routes/index.tsx @@ -11,6 +11,7 @@ import { BookOpen, Users, Heart, + Play, } from "lucide-react"; export const Route = createFileRoute("/")({ @@ -85,6 +86,15 @@ function Home() { Get Started + + + + Demo +
@@ -228,6 +238,7 @@ function Home() { params={{ _splat: "setup/installation" }} className="inline-flex items-center gap-2 rounded-lg bg-fd-primary px-5 py-2.5 text-sm font-medium text-fd-primary-foreground transition-opacity hover:opacity-90" > + Read Documentation + GitHub View on GitHub