feat(ci): added netlify toml to correctly build astro (#176)

## Summary
This pull request introduces comprehensive documentation and
configuration updates to clarify and standardize deployment processes
for the Interledger Developers Portal. The main focus is on improving
developer onboarding, ensuring deployment consistency between preview
and production environments, and deprecating outdated workflows. Below
are the most important changes grouped by theme:

**Documentation & Developer Guidance**

* Added a new `.github/copilot-instructions.md` file detailing project
architecture, deployment procedures, configuration notes, common
pitfalls, and development philosophy to help contributors and AI agents
understand the project.
* Updated `README.md` to include clear explanations of both Netlify
preview deployments and Google Cloud production deployments, as well as
guidance on legacy workflow deprecation.

**Deployment Configuration**

* Added a new `netlify.toml` configuration file that standardizes the
build process using Bun, ensures the build output is nested under
`_netlify/builders/developers`, and sets up redirect rules for proper
client-side routing under the `/developers` base path.

**Workflow Deprecation**

* Marked `.github/workflows/deploy.yml` as deprecated, directing
contributors to use the new Google Cloud deployment workflow instead.

Author: bosbaber

.github/copilot-instructions.md

@@ -0,0 +1,69 @@
+# GitHub Copilot Instructions for Interledger Developers Portal
+
+## Project Overview
+
+This is the Interledger Developers Portal, a documentation site built with [Astro](https://astro.build/) and [Starlight](https://starlight.astro.build/). It serves as the `/developers` section of [interledger.org](https://interledger.org/).
+
+**⚠️ Important**: When a deployment configuration, build process, or new gotcha is discovered, please update this file to keep it accurate. This helps AI agents and future contributors understand the project correctly.
+
+## Architecture
+
+- **Framework**: Astro with Starlight documentation framework
+- **Package Manager**: Bun (not npm/yarn)
+- **Build Output**: `dist/` directory
+- **Base Path**: `/developers` (configured in `astro.config.mjs`)
+
+## Deployment
+
+### Preview (Netlify)
+- Every PR generates an automatic preview at `https://deploy-preview-{PR}--developers-preview.netlify.app/developers/`
+- Configured via `netlify.toml`
+- Build command: `npm install -g bun && bun install && bun run build`
+- **Important**: Build output is copied to `_netlify/builders/developers/` to serve at `/developers/` path
+- Redirect rules route `/developers/*` to `/developers/index.html` for client-side routing
+
+### Production (Google Cloud)
+- Deployed to `https://interledger.org/developers/` via Google Cloud Storage
+- Triggered automatically on merge to `main` by `.github/workflows/deploy_gcs.yml`
+- Process: Build → Deploy to GCS → Rebuild nginx-rewrite Cloud Run service → Invalidate CDN
+- **Legacy**: `deploy.yml` exists but is deprecated - use `deploy_gcs.yml`
+
+## Key Development Notes
+
+### Configuration
+- **`astro.config.mjs`**: Defines site structure, integrations, and plugins. Base path is hardcoded to `/developers`
+- **`netlify.toml`**: Handles Netlify-specific build and deployment configuration with path rewrites
+- Keep both Astro config and Netlify config in sync when changing base paths or build output
+
+### Static Assets
+- Public files go in `public/` directory
+- Images should reference paths like `/developers/img/filename.png` (includes the base path)
+- Scripts in `public/scripts/` are referenced with full `/developers/scripts/` path
+
+### Content
+- Blog posts: `src/content/blog/`
+- Documentation: `src/content/docs/`
+- Components: `src/components/`
+- Layouts: `src/layouts/`
+- Starlight documentation framework handles sidebar, search, and routing automatically
+
+### Common Commands
+- `bun run start` - Local dev server at `localhost:1103`
+- `bun run build` - Build to `dist/`
+- `bun run format` - Fix code formatting and linting
+- `bun run lint` - Check code formatting and linting
+
+## Development Philosophy
+
+- Keep the `/developers` base path consistent across all configurations
+- Netlify preview should match production behavior exactly - both serve at `/developers/`
+- Always test builds locally before pushing: `bun run build && bun run preview`
+- Use Bun for all package management - don't mix with npm/yarn
+- Link validation is enabled locally but disabled on Netlify (see `astro.config.mjs`)
+
+## Common Pitfalls
+
+1. **Asset paths**: Don't forget the `/developers` prefix in asset URLs
+2. **Base path changes**: If modifying base path, update both `astro.config.mjs` AND the Netlify build output path logic
+3. **Package manager**: Use `bun install`, not `npm install`
+4. **Netlify preview**: Output must be nested under `/developers` in publish directory - this is why we copy to `_netlify/builders/developers/`

.github/workflows/deploy.yml

@@ -1,3 +1,4 @@
+# NOTE THAT THIS SCRIPT WILL BE DEPRECATED SOON. PLEASE USE THE NEW WORKFLOW IN `.github/workflows/deploy_gcs.yml` INSTEAD.
 name: Deploy to AWS
 
 on:

README.md

@@ -69,7 +69,30 @@ ESLint is configured to work with TypeScript and Astro files. The configuration
 
 ### 👀 Want to learn more?
 
-Check out [Starlight’s docs](https://starlight.astro.build/), read [the Astro documentation](https://docs.astro.build), or jump into the [Astro Discord server](https://astro.build/chat).
+Check out [Starlight's docs](https://starlight.astro.build/), read [the Astro documentation](https://docs.astro.build), or jump into the [Astro Discord server](https://astro.build/chat).
+
+## Deployment Notes
+
+This project has two deployment mechanisms:
+
+### Preview Deployments (Netlify)
+
+Every pull request automatically generates a preview deployment on Netlify at `https://deploy-preview-{PR_NUMBER}--developers-preview.netlify.app/developers/`. This allows reviewers to see changes before they're merged. The Netlify configuration is defined in `netlify.toml`.
+
+### Production Deployments (Google Cloud Storage)
+
+The real production deployment is served through Google Cloud Storage (GCS) at `https://interledger.org/developers/` as part of the main Interledger website. This is a transparent proxy configuration - the developers portal is hosted separately but appears as part of the main domain.
+
+When a PR is merged to the `main` branch, the `.github/workflows/deploy_gcs.yml` GitHub Actions workflow automatically:
+
+1. Builds the site using Bun
+2. Deploys the built files to Google Cloud Storage (`gs://interledger-websites-public/developers`)
+3. Rebuilds and deploys the nginx-rewrite Cloud Run service (which handles the `/developers` proxy routing)
+4. Invalidates the CDN cache to ensure new content is served immediately
+
+**Note:** There is a legacy `deploy.yaml` workflow in `.github/workflows/` which is being deprecated. New deployments should use `deploy_gcs.yml`.
+
+For more information about the main Interledger.org infrastructure and deployment pipeline, see the [`interledger.org-v4`](https://github.com/interledger/interledger.org-v4) repository.
 
 Thank You for Contributing! We appreciate your effort to write a blog post and share your expertise with the community!