This is an automated email from the ASF dual-hosted git repository. maximebeauchemin pushed a commit to branch codespaces in repository https://gitbox.apache.org/repos/asf/superset.git
commit e6e0c3c47e250ca374580bcedbf257415bc33b17 Author: Maxime Beauchemin <[email protected]> AuthorDate: Tue Jul 29 10:19:01 2025 -0700 docs --- .devcontainer/README.md | 111 +-------------------------------- docs/docs/contributing/development.mdx | 72 +++++++++++++++++++++ 2 files changed, 75 insertions(+), 108 deletions(-) diff --git a/.devcontainer/README.md b/.devcontainer/README.md index 93deb0bc2d..6b24183edc 100644 --- a/.devcontainer/README.md +++ b/.devcontainer/README.md @@ -1,110 +1,5 @@ -# Superset GitHub Codespaces Development +# Superset Development with GitHub Codespaces -This configuration provides a full development environment with Docker-in-Docker support, allowing you to run `docker-compose-light.yml` inside your Codespace for lightweight, multi-instance development. +For complete documentation on using GitHub Codespaces with Apache Superset, please see: -## Quick Start - -1. **Create a Codespace** from this repo (click "Code" → "Codespaces" → "Create codespace") -2. **Wait for setup** (~3-5 minutes first time) -3. **Start Superset**: - ```bash - docker-compose -p ${CODESPACE_NAME} -f docker-compose-light.yml up - ``` -4. **Access Superset** at the forwarded port 9001 URL (auto-opens) - -## Connecting to Your Codespace - -### VS Code Desktop -1. Install [GitHub Codespaces extension](https://marketplace.visualstudio.com/items?itemName=GitHub.codespaces) -2. Open Command Palette (`Cmd/Ctrl+Shift+P`) -3. Run "Codespaces: Connect to Codespace" -4. Select your Codespace - -### SSH Access -```bash -# Install GitHub CLI if needed -brew install gh # macOS -# or visit: https://cli.github.com/ - -# Login to GitHub -gh auth login - -# List your Codespaces -gh cs list - -# SSH into a Codespace -gh cs ssh -c <codespace-name> - -# Or use the interactive selector -gh cs ssh -``` - -### Web Browser -- Go to https://github.com/codespaces -- Click on your Codespace to open in browser - -## Running Multiple Instances - -Perfect for testing different branches/features simultaneously: - -```bash -# Instance 1 (in Codespace 1) -docker-compose -p feature1 -f docker-compose-light.yml up - -# Instance 2 (in Codespace 2) -NODE_PORT=9002 docker-compose -p feature2 -f docker-compose-light.yml up -``` - -## Why docker-compose-light.yml? - -- **Faster startup**: No Redis, nginx, or unnecessary services -- **Lower resources**: Important for Codespaces quotas -- **Isolated databases**: Each instance gets its own `superset_light` database -- **Simple access**: Single port (9001) with frontend proxy to backend - -## Port Forwarding & URLs - -When Superset starts, Codespaces automatically forwards port 9001: -- **Public URL**: `https://<codespace-name>-9001.app.github.dev` -- **Visibility**: Private by default (requires GitHub auth) -- **Make public**: Click port in "Ports" tab → Change visibility - -To forward additional ports: -```bash -# From outside the Codespace -gh cs ports forward 5432:5432 -c <codespace-name> # PostgreSQL -gh cs ports forward 8088:8088 -c <codespace-name> # Backend API -``` - -## Tips for Claude Code Usage - -When using `claude --yes` in Codespaces: -- All changes are isolated to your Codespace -- Database/volumes are separate from your local machine -- Can safely run destructive commands -- Easy to delete and recreate if needed - -## Credentials - -Default login (same as docker setup): -- Username: `admin` -- Password: `admin` - -## Resource Usage - -The light compose typically uses: -- ~2GB RAM (vs ~4GB for full stack) -- Minimal CPU when idle -- ~2GB disk for database + dependencies - -## Troubleshooting - -If services fail to start: -```bash -# Check logs -docker-compose -f docker-compose-light.yml logs - -# Restart fresh -docker-compose -f docker-compose-light.yml down -v -docker-compose -f docker-compose-light.yml up -``` +**[Setting up a Development Environment - GitHub Codespaces](https://superset.apache.org/docs/contributing/development#github-codespaces-cloud-development)** diff --git a/docs/docs/contributing/development.mdx b/docs/docs/contributing/development.mdx index ff0b6633fb..fe8995d28a 100644 --- a/docs/docs/contributing/development.mdx +++ b/docs/docs/contributing/development.mdx @@ -120,6 +120,78 @@ docker volume rm superset_db_home docker-compose up ``` +## GitHub Codespaces (Cloud Development) + +GitHub Codespaces provides a complete, pre-configured development environment in the cloud. This is ideal for: +- Quick contributions without local setup +- Consistent development environments across team members +- Working from devices that can't run Docker locally +- Safe experimentation in isolated environments + +:::info +We're grateful to GitHub for providing this excellent cloud development service that makes +contributing to Apache Superset more accessible to developers worldwide. +::: + +### Getting Started with Codespaces + +1. **Create a Codespace**: Use this pre-configured link that sets up everything you need: + + [**Launch Superset Codespace →**](https://github.com/codespaces/new?skip_quickstart=true&machine=standardLinux32gb&repo=39464018&ref=codespaces&geo=UsWest&devcontainer_path=.devcontainer%2Fdevcontainer.json) + + :::caution + **Important**: You must select at least the **4 CPU / 16GB RAM** machine type (pre-selected in the link above). + Smaller instances will not have sufficient resources to run Superset effectively. + ::: + +2. **Wait for Setup**: The initial setup takes several minutes. The Codespace will: + - Build the development container + - Install all dependencies + - Start all required services (PostgreSQL, Redis, etc.) + - Initialize the database with example data + +3. **Access Superset**: Once ready, check the **PORTS** tab in VS Code for port `9001`. + Click the globe icon to open Superset in your browser. + - Default credentials: `admin` / `admin` + +### Key Features + +- **Auto-reload**: Both Python and TypeScript files auto-refresh on save +- **Pre-installed Extensions**: VS Code extensions for Python, TypeScript, and database tools +- **Multiple Instances**: Run multiple Codespaces for different branches/features +- **SSH Access**: Connect via terminal using `gh cs ssh` or through the GitHub web UI +- **VS Code Integration**: Works seamlessly with VS Code desktop app + +### Managing Codespaces + +- **List active Codespaces**: `gh cs list` +- **SSH into a Codespace**: `gh cs ssh` +- **Stop a Codespace**: Via GitHub UI or `gh cs stop` +- **Delete a Codespace**: Via GitHub UI or `gh cs delete` + +### Debugging and Logs + +Since Codespaces uses `docker-compose-light.yml`, you can monitor all services: + +```bash +# Stream logs from all services +docker compose -f docker-compose-light.yml logs -f + +# Stream logs from a specific service +docker compose -f docker-compose-light.yml logs -f superset + +# View last 100 lines and follow +docker compose -f docker-compose-light.yml logs --tail=100 -f + +# List all running services +docker compose -f docker-compose-light.yml ps +``` + +:::tip +Codespaces automatically stop after 30 minutes of inactivity to save resources. +Your work is preserved and you can restart anytime. +::: + ## Installing Development Tools :::note
