Merge pull request #25 from PurdueRCAC/docs

Updating the documentation

Author: skkra0

.github/workflows/publish-docs.yml

@@ -0,0 +1,49 @@
+# Taken from https://github.com/withastro/github-pages/blob/main/.github/workflows/deploy.yml
+
+name: Publish Documentation
+
+on:
+  # Trigger the workflow every time you push to the `main` branch
+  # Using a different branch name? Replace `main` with your branch’s name
+  push:
+    branches: [main]
+    paths:
+      - "docs/**"
+  # Allows you to run this workflow manually from the Actions tab on GitHub.
+  workflow_dispatch:
+
+# Allow this job to clone the repo and create a page deployment
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+# Allow one concurrent deployment
+concurrency:
+  group: "pages"
+  cancel-in-progress: true
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout your repository using git
+        uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8 # v6.0.1
+      - name: Install, build, and upload your site output
+        uses: withastro/action@fc88a7002f0c62327f26fb1b15f2a1d581249278 # v5.1.0
+        with:
+          path: docs # The root location of your Astro project inside the repository. (optional)
+          node-version: 24 # The specific version of Node that should be used to build your site. Defaults to 22. (optional)
+          # package-manager: pnpm@latest # The Node package manager that should be used to install dependencies and build your site. Automatically detected based on your lockfile. (optional)
+          # build-cmd: pnpm run build # The command to run to build your site. Runs the package build script/task by default. (optional)
+
+  deploy:
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@d6db90164ac5ed86f2b6aed7e0febac5b3c0c03e # v4.0.5

backend/src/service/helper/deploymentConfig.ts

@@ -355,7 +355,7 @@ export class DeploymentConfigService {
   }
 
   private async validateSubdomain(subdomain: string, existingAppId?: number) {
-    if (subdomain.length > MAX_SUBDOMAIN_LEN || !isRFC1123(subdomain)) {
+    if (!isRFC1123(subdomain)) {
       throw new ValidationError(
         "Subdomain must contain only lowercase alphanumeric characters or '-', " +
           "start and end with an alphanumeric character, " +

docs/astro.config.mjs

@@ -5,7 +5,7 @@ import starlightLinksValidator from "starlight-links-validator";
 
 // https://astro.build/config
 export default defineConfig({
-  site: "https://docs.anvilcloud.rcac.purdue.edu",
+  site: "https://purduercac.github.io/AnvilOps",
   integrations: [
     starlight({
       plugins: [starlightLinksValidator()],

docs/src/content/docs/guides/deploying-a-database.md

@@ -12,7 +12,7 @@ We will learn:
 
 ## 1. Create an App
 
-Navigate to the [Create App form](https://anvilops.rcac.purdue.edu/create-app).
+Navigate to the Create App form for [Anvil Composable](https://anvilops.rcac.purdue.edu/create-app) or [Geddes](https://anvilops.geddes.rcac.purdue.edu/create-app).
 
 Select an organization and a Rancher project.
 
@@ -25,9 +25,7 @@ This tells AnvilOps to pull a Postgres image from Docker Hub and deploy it in th
 
 ## 3. Configure Deployment Options
 
-Set the **Public URL** subdomain to a unique name. Postgres communicates with clients over TCP, not HTTP, so it will not be publicly accessible at this URL.
-Instead, we will need to use the cluster-internal hostname below. In this screenshot, that's `anvilops-pg-example.anvilops-pg-example.svc.cluster.local`.
-**Write down this value. We will need it to connect to the database.**
+Uncheck the box labeled `Make my app public` since our database is not a web application.
 
 Set the port number to `5432` so that AnvilOps knows which port to expose outside of the Postgres container.
 
@@ -59,32 +57,38 @@ We use volume mounts to specify the paths we want to keep when the app is update
 
 Consider the file system to be ephemeral except the paths included in your volume mounts.
 
-## 6. Connect to the Database
+## 6. (Optional) Set the namespace
+
+Open the Advanced dropdown. AnvilOps will have already filled in a unique namespace for your application, which you can edit. Your application will be reachable from within the cluster at `<namespace>.<namespace>.svc.cluster.local`.
+
+![](./deploying-a-database/advanced-options.png)
+
+## 7. Connect to the Database
 
 Recall the internal address you created earlier.
-In this example, it's `anvilops-pg-example.anvilops-pg-example.svc.cluster.local`. It should follow the form `anvilops-{subdomain}.anvilops-{subdomain}.svc.cluster.local`, where `{subdomain}` is what you typed into the Public URL field.
+In this example, it's `pg-example.pg-example.svc.cluster.local`.
 
-Let's create a connection string from this hostname. We can connec to the database at:
+Let's create a connection string from this hostname. We can connect to the database at:
 
 ```
-postgresql://anvilops:password@anvilops-pg-example.anvilops-pg-example.svc.cluster.local:80
+postgresql://anvilops:password@pg-example.pg-example.svc.cluster.local:80
 ```
 
 Assuming these values:
 
-- Host: `anvilops-pg-example.anvilops-pg-example.svc.cluster.local`
+- Host: `pg-example.pg-example.svc.cluster.local`
 - Port: `80` (The port must be set to 80. AnvilOps always exposes your service at port 80 within the cluster.)
 - Username: `anvilops` (from the environment variable you set in Step 4)
 - Password: `password` (from the environment variable you set in Step 4)
 
-Any application running in the same Kubernetes cluster can now access your database with this connection string.
+Applications will access your database with this connection string. We recommend deploying an application that connects to this database through AnvilOps and adding them to the same app group. Using a network policy, AnvilOps will ensure that the two can communicate.
 
-If you want to access your database from another AnvilOps app, we recommend placing your connection string in an environment variable and marking it as sensitive.
+If you want to access your database from another AnvilOps app, we recommend placing your connection string in its environment variables and marking it as sensitive.
 
 ## Limitations
 
 1. This deployment is not designed to scale past one replica. **Do not increase the `Replicas` field.** In AnvilOps, a unique volume is created for every replica, so the instances will not be able to share information.
 
    In most cases, you can get away with scaling vertically by increasing the app's CPU and memory limits.
 
-2. AnvilOps does not expose non-HTTP services to the public. Your database will not be accessible at the "Public URL" because Postgres uses TCP to communicate with clients.
+2. AnvilOps does not expose non-HTTP services, such as Postgres, to the public.

docs/src/content/docs/guides/deploying-a-database/advanced-options.png

@@ -6,34 +6,36 @@ sidebar:
 
 This tutorial will demonstrate:
 
-- How to deploy one of AnvilOps' template applications on Anvil Composable.
+- How to deploy one of AnvilOps' template applications.
 - How to use Railpack to build applications without a Dockerfile.
 - How to use AnvilOps' GitHub integrations for continuous deployment.
 
-Follow along at `https://anvilops.rcac.purdue.edu`.
+Follow along at [`https://anvilops.rcac.purdue.edu`](https://anvilops.rcac.purdue.edu) or [`https://anvilops.geddes.rcac.purdue.edu`](https://anvilops.geddes.purdue.edu).
 
 ### Prerequisites
 
 You will need to have the AnvilOps GitHub App installed for your organization. This allows AnvilOps to deploy repositories on the cluster. In particular, for this tutorial, the GitHub App is needed for AnvilOps to clone the template repository to your account.
 
-If you do not have access to your own project on Anvil Composable, select the `anvilops_sandbox` project.
+If you do not have access to your own project on Anvil Composable, select the `anvilops_sandbox` project. This project can be used temporarily for tests and tutorials, but applications deployed to this project may be deleted at any time.
 
 ### Initial Configuration
 
 1. Click the Create App button on the AnvilOps dashboard.
    ![Create App buttons](./tutorial/create-app-buttons.png)
 
-2. After selecting an Organization (and a Rancher project), select `Git Repository` as the Deployment Source.
+2. Select a Rancher project to deploy the application into. A project is a grouping of applications within a Kubernetes cluster. If you do not have access to your own project on Anvil Composable, select the `anvilops_sandbox` project.
 
-3. Click the repository dropdown, and select `External Git Repository`.
+3. Select `Git Repository` as the Deployment Source. If the form prompts you to install the GitHub App on your organization, click the button and follow the instructions. The AnvilOps GitHub App allows AnvilOps to clone repositories to your account as well as redeploy applications in response to events.
 
-4. Select the `AnvilOps Demo` template app. You will be prompted to import the `anvilops-demo` repository to your account.
+4. Click the repository dropdown, and select `External Git Repository`.
+
+5. Select the `AnvilOps Demo` template app. You will be prompted to import the `anvilops-demo` repository to your account.
 
    The default settings configure AnvilOps to automatically redeploy your application when a new commit is pushed to the `main` branch of your repository.
 
    ![Settings for a deployment of the AnvilOps Demo app from a Git repository. The branch is set to main, and the event is set to push.](./tutorial/git-demo.png)
 
-5. Look over the settings that have been autofilled.
+6. Look over the settings that have been autofilled.
 
    **Build**: AnvilOps will use Railpack to detect the framework the repository uses([Astro](https://astro.build/)) and build it without extra configuration.
 
@@ -43,8 +45,8 @@ If you do not have access to your own project on Anvil Composable, select the `a
 
    ![Build and deployment options for the AnvilOps demo app. The builder is Railpack, the subdomain is anvilops-demo-96ynq, and the port number is 80.](./tutorial/git-build-deploy.png)
 
-6. Click `Deploy`. In a few minutes, the application should be up and running at \
-   `https://<subdomain>.anvilcloud.rcac.purdue.edu`.
+7. Click `Deploy`. In a few minutes, the application should be up and running at \
+   `https://<subdomain>.anvilcloud.rcac.purdue.edu`, or `https://<subdomain>.geddes.rcac.purdue.edu`.
 
    ![A screenshot of the AnvilOps demo web app.](./tutorial/anvilops-git-demo-app.png)
 
@@ -59,4 +61,4 @@ Try pushing a commit to the repository to see how AnvilOps updates the deploymen
 3. Go back to the dashboard for your app in AnvilOps. Under `Recent Deployments`, you should see a new entry. If you click the `Logs` button for that deployment, you can watch the logs as AnvilOps rebuilds the application.
    ![A screenshot of the recent deployments for an AnvilOps app. The latest entry has the status Building.](./tutorial/git-recent-deployments.png)
 
-4. When the build completes, go back to `https://<subdomain>.anvilcloud.rcac.purdue.edu` and reload the page. It should have the updated text.
+4. When the build completes, reopen your application and reload the page. It should have the updated text.

docs/src/content/docs/guides/deploying-a-database/deployment-options.png

@@ -9,7 +9,7 @@ This tutorial will demonstrate:
 
 - How to deploy an application from a preexisting container image.
 
-Follow along at `https://anvilops.rcac.purdue.edu`.
+Follow along at [`https://anvilops.rcac.purdue.edu`](https://anvilops.rcac.purdue.edu) or [`https://anvilops.geddes.rcac.purdue.edu`](https://anvilops.geddes.rcac.purdue.edu).
 
 ### Getting started
 
@@ -18,17 +18,17 @@ Follow along at `https://anvilops.rcac.purdue.edu`.
 
 2. After selecting an Organization (and a Rancher project), select `OCI Image` as the Deployment Source.
 
-3. Enter a container image. The image reference should look like `REGISTRY/NAMESPACE/REPOSITORY:TAG`.
+3. Enter a container image. The image reference should look like `HOST/NAMESPACE/REPOSITORY:TAG`.
 
-   If you are deploying an image available on Docker Hub, you can omit the host. If the image is a Docker Official image, you can omit the repository as well. However, it's strongly advised to use Anvil's [Docker Hub cache](https://www.rcac.purdue.edu/knowledge/anvil/composable/registry#_using_the_anvil_registry_docker_hub_cache) instead.
+   Where possible, it is strongly advised to use Anvil's [Docker Hub cache](https://www.rcac.purdue.edu/knowledge/anvil/composable/registry#_using_the_anvil_registry_docker_hub_cache) instead of pulling directly from Docker Hub to avoid rate limiting.
 
    Some example container image references:
 
-   - `registry.anvil.rcac.purdue.edu/anvilops/foo:bar`
+   - `registry.anvil.rcac.purdue.edu/docker-hub-cache/postgis:latest`
      - Host: `registry.anvil.rcac.purdue.edu`
-     - Namespace: `anvilops`
-     - Image: `foo`
-     - Tag: `bar`
+     - Namespace: `docker-hub-cache`
+     - Image: `postgis`
+     - Tag: `latest`
    - `nginx:1.28-alpine`
      - Host: `docker.io` (default)
      - Namespace: `library` (default)
@@ -37,9 +37,9 @@ Follow along at `https://anvilops.rcac.purdue.edu`.
 
 ### Deployment options
 
-4. Select a unique subdomain for your app. Your app will be made publicly accessible at `https://<subdomain>.anvilcloud.rcac.purdue.edu`.
+4. Choose whether to expose your app publicly, and if so, select a subdomain. Your app will be made publicly accessible at `https://<subdomain>.anvilcloud.rcac.purdue.edu`, or `https://<subdomain>.geddes.rcac.purdue.edu`.
 
-5. Enter the port number your application listens on. Kubernetes will route requests to `https://<subdomain>.anvilcloud.rcac.purdue.edu` to this port for your applications to process.
+5. Enter the port number your application listens on. Kubernetes will route requests to this port for your application to process.
 
 6. Add any environment variables your app requires. Environment variables can be marked as sensitive. Sensitive environment variables cannot be viewed after they are set, although they can be updated.
 

docs/src/content/docs/guides/from-github.md

@@ -6,22 +6,7 @@ sidebar:
 
 import { Steps } from "@astrojs/starlight/components";
 
-If you would like to deploy an application on Anvil Composable, follow these instructions on `https://anvilops.rcac.purdue.edu`. If you would like to deploy on Geddes, follow these instructions on `https://anvilops.geddes.rcac.purdue.edu`.
-
-## Setting Up Your Account
-
-<Steps>
-
-1. Sign in to AnvilOps.
-   This will create an AnvilOps account for you.
-
-2. Navigate to the dashboard page.
-3. Link your GitHub organization or personal account.
-
-   This will allow you to deploy applications from GitHub repositories.
-   Make sure you grant the AnvilOps GitHub App permission to access any repositories you want to deploy!
-
-</Steps>
+If you would like to deploy an application on Anvil Composable, follow along at [`https://anvilops.rcac.purdue.edu`](https://anvilops.rcac.purdue.edu). If you would like to deploy on Geddes, follow these instructions on [`https://anvilops.geddes.rcac.purdue.edu`](https://anvilops.geddes.rcac.purdue.edu).
 
 ## Creating an App
 
@@ -40,6 +25,8 @@ If you would like to deploy an application on Anvil Composable, follow these ins
 
 Navigate to the Create App page in order to configure and launch your app. You will need to select your Project, the repository or image you would like to deploy, a subdomain, and the port number of the application.
 
+If your app is a web application, you can make it publicly accessible at an available subdomain of your choice. Otherwise, uncheck the `Make my app public` box.
+
 If you are deploying a Git repository, you will need to specify the build configuration.
 
 If your repository already contains a Dockerfile, select the `Dockerfile` option and provide the path to the file. For instance, if the Dockerfile is in the root directory of your application, enter `Dockerfile`.