From 21fcc14e4c3f28f89b21698c4b17b654ab2100c2 Mon Sep 17 00:00:00 2001 From: Morgan Roderick Date: Fri, 12 Jun 2026 14:13:18 +0200 Subject: [PATCH] docs: simplify local development setup for junior contributors Make native installation the officially recommended path for local development. Docker is moved to a secondary, not-recommended section. Changes: - Rewrite README.md with native installation as the quick-start path - Add docs/development-setup.md: comprehensive, junior-friendly guide covering macOS and Linux, with troubleshooting for common issues - Add lib/tasks/setup.rake: rake setup:check command that inspects the environment and reports exactly what is missing or misconfigured - Add docs/coding-agent-setup-skill.md: skill file for AI coding agents (Codex, Claude, Pi, etc.) to help contributors diagnose setup issues - Add make check target that delegates to rake setup:check - Update db/seeds.rb to reference the new docs path - Remove native-installation-instructions.md (content merged into the new guide) The setup:check task verifies: - Ruby version, Bundler, mise, PostgreSQL, ImageMagick - GitHub OAuth credentials in mise.local.toml - Bundle dependencies, database connection, migrations, test database --- Makefile | 3 + README.md | 186 +++++++------- db/seeds.rb | 2 +- docs/coding-agent-setup-skill.md | 115 +++++++++ docs/development-setup.md | 381 ++++++++++++++++++++++++++++ lib/tasks/setup.rake | 236 +++++++++++++++++ native-installation-instructions.md | 101 -------- 7 files changed, 828 insertions(+), 196 deletions(-) create mode 100644 docs/coding-agent-setup-skill.md create mode 100644 docs/development-setup.md create mode 100644 lib/tasks/setup.rake delete mode 100644 native-installation-instructions.md diff --git a/Makefile b/Makefile index 1107a5681..6340e93d3 100644 --- a/Makefile +++ b/Makefile @@ -25,3 +25,6 @@ serve: test: bundle exec parallel_rspec spec/ -n 3 + +check: + bundle exec rake setup:check diff --git a/README.md b/README.md index 65880dc9c..4333002a6 100644 --- a/README.md +++ b/README.md @@ -11,120 +11,118 @@ If you are considering making a PR, please take a look at the [GitHub issues](ht ## Getting Started -The following steps walk through getting the application running. Before you start, please check out our [contributing guidelines](https://github.com/codebar/planner/blob/master/CONTRIBUTING.md). +Before you start, please check out our [contributing guidelines](https://github.com/codebar/planner/blob/master/CONTRIBUTING.md). + +We recommend **native installation** for local development. A full step-by-step guide is in [docs/development-setup.md](docs/development-setup.md). The quick version is below. + +### Quick start + +1. **Install prerequisites** (macOS or Linux): + - [mise](https://mise.jdx.dev/) — manages Ruby and environment variables + - [PostgreSQL](https://www.postgresql.org/) — database server + - [ImageMagick](https://imagemagick.org/) — image processing + + On macOS with Homebrew: + ```bash + brew install mise postgresql imagemagick + brew services start postgresql + ``` + +2. **Clone the project**: + ```bash + git clone https://github.com/codebar/planner.git + cd planner + ``` + +3. **Install Ruby** (managed by mise): + ```bash + mise install + ``` + +4. **Configure GitHub OAuth**: + - Create a GitHub OAuth app at [https://github.com/settings/applications/new](https://github.com/settings/applications/new) + - Authorization callback URL: `http://localhost:3000/auth/github` + - Copy your Client ID and Client Secret into `mise.local.toml`: + ```bash + cp mise.local.toml.example mise.local.toml + # Edit mise.local.toml with your real credentials + ``` + +5. **Install dependencies and set up the database**: + ```bash + gem install bundler + bundle install + bundle exec rake db:create db:migrate db:test:prepare + ``` + +6. **Check your environment**: + ```bash + bundle exec rake setup:check + ``` + +7. **Start the app**: + ```bash + bundle exec rails server + ``` + + Visit [http://localhost:3000](http://localhost:3000). + +### Run the tests -1. [Clone the project](#1-clone-the-project) -2. [Enable GitHub Authentication](#2-enable-github-authentication) -3. [Install and set up the environment using docker](#3-install-and-set-up-the-environment-using-docker) -4. [Start the app](#4-start-the-app) -5. [Run the tests](#5-run-the-tests) - -### 1. Clone the project - -1. Navigate to your project's chosen parent directory, e.g. `cd ~/Documents/codebar` -2. [Clone the project](https://help.github.com/articles/cloning-a-repository/), e.g. `git clone git@github.com:codebar/planner.git` -3. Navigate into the project directory: `cd planner` - -### 2. Enable GitHub Authentication - -The application uses GitHub OAuth for user authentication. You'll need to create a new OAuth application on your GitHub account, then add the key and secret to your project's environment variables. - -#### Create a new Github OAuth application - -Visit [https://github.com/settings/applications/new](https://github.com/settings/applications/new) and fill out the form to create a new application. Use these field values: - -| Field | Value | -| --- | --- | -| Application name | Something memorable, like 'codebar planner' | -| Homepage URL | `http://localhost:3000` | -| Application description | Something memorable, like 'Local codebar app authentication'. | -| Authorization Callback URL | `http://localhost:3000/auth/github` | - -#### Add your application details to your environment variables - -**Native installation (recommended):** Copy `mise.local.toml.example` to `mise.local.toml` -and fill in your GitHub key and secret: - -``` -cp mise.local.toml.example mise.local.toml -# Edit mise.local.toml with your values +```bash +bundle exec rspec ``` -Environment variables are managed by [mise](https://mise.jdx.dev). Install it -with `brew install mise` and enable `mise activate` in your shell profile. - -**Docker installation:** Copy `docker-compose.override.yml.example` to -`docker-compose.override.yml` and fill in your GitHub key and secret: - -``` -cp docker-compose.override.yml.example docker-compose.override.yml -# Edit docker-compose.override.yml with your values +Run tests in parallel for faster results: +```bash +bundle exec parallel_rspec spec/ -n 3 ``` -Docker Compose automatically merges this file — no extra configuration needed. - -### 3. Install and set up the environment using docker - -We recommend using Docker to install and run the application. However alternatively if you prefer, [you can install directly to your system environment instead](./native-installation-instructions.md). - -Before you start, you will need to have Docker installed and running. You can [download it from the Docker website](https://docker.com/). Once downloaded, install and start the Docker application. - -Run `bin/dup` to build and create the docker container. This will also set up the Rails application within the container and start the container. You will only have to run this command once. After initial setup, use `bin/dstart` to start an existing container - using `bin/dup` will recreate an existing container and reset the database. - -**Note:** The Docker setup includes ImageMagick automatically. If you're using native installation, you must install ImageMagick separately (see [native-installation-instructions.md](./native-installation-instructions.md)). - -### 4. Start the app - -Run `bin/dserver` to start the Rails server. - -*If you have previously stopped the container, you will have to first start the container using `bin/dstart`. - -This should run a process which starts a server in a Docker container on your computer. This process won't finish - you'll know the server is ready when it stops doing anything and displays a message like this: -``` -Rails 4.2.11 application starting in development on http://localhost:3000 +Run a single test: +```bash +bundle exec rspec spec/path/to/test_spec.rb:42 ``` -(Optional) Note that to be able to use the page as an admin, you must first give yourself admin privileges. Make sure you have started your app and signed up as an user on your locally running app. Then run the script `bin/dadmin `. - -**You can now view the app at http://localhost:3000** +Run JavaScript-enabled feature tests with a visible browser: +```bash +PLAYWRIGHT_HEADLESS=false bundle exec rspec +``` -You can stop the server when you're finished by typing `Ctrl + C`. +### Make yourself an admin -### 5. Run the tests +After signing up locally, run: +```bash +bundle exec rails runner "Member.find_by(email: 'your-email@example.com').add_role(:admin)" +``` -Run `bin/drspec` to run all the tests. +### Full setup guide -This command passes any additional arguments into `rspec` in the docker container, so you can run individual tests with `bin/drspec PATH_TO_TEST` and run a single test case in a file with `bin/drspec PATH_TO_TEST:LINE_NUMBER` +For detailed, step-by-step instructions — including troubleshooting, Linux-specific steps, and explanations of what each tool does — see [docs/development-setup.md](docs/development-setup.md). -#### Running JavaScript enabled feature tests with a visible browser +--- -There are a small number of feature tests marked with `js: true` which use -headless Chrome. These can be hard to work with without being able to see what is -actually happening in the browser. To spin up a visible browser, pass -`CHROME_HEADLESS=false` as part of the test command, for example: +## Docker (not recommended) -```bash -CHROME_HEADLESS=false bundle exec rspec -``` +A Docker setup exists but is **not recommended** for local development. It is slower, harder to debug, and does not support running JavaScript feature tests with a visible browser. -Running JavaScript enabled tests with a visible browser currently doesn't work with Docker. +If you prefer Docker, see the commands in `bin/d*`: -### Available Docker commands +| Command | What it does | +|---------|-------------| +| `bin/dup` | Build and start a new container (also resets the database) | +| `bin/dstart` | Start an existing container | +| `bin/dserver` | Run the Rails server inside the container | +| `bin/drspec` | Run the test suite inside the container | +| `bin/drake` | Run rake inside the container | +| `bin/dexec` | Open a shell inside the container | +| `bin/dstop` | Stop the container | +| `bin/ddown` | Stop and remove the container | -- `bin/dup`: `docker-compose up --build -d --wait && rake db:drop db:create db:migrate db:seed db:test:prepare`. Rebuilds and boots up a new container, and then initialize the Rails database. -- `bin/dstart`: `docker-compose start`. Starts the existing container. -- `bin/dserver`: `docker-compose exec web make serve`. Runs the Rails server. Use this instead of `bin/drails server` to make it bind to the correct IP addresses to allow the server to be viewable outside the container. -- `drails`: `docker-compose exec web rails $@`. Runs rails within the container. -- `drspec`: `docker-compose exec web rspec $@`. Runs rspec within the container. -- `drake`: `docker-compose exec web rake $@`. Runs rake inside the container. -- `dexec`: `docker-compose exec web bash`. Runs a bash shell inside the container. -- `dadmin`: Gives the the last user (or the one with a given email) the admin role -- `bin/dstop`: `docker-compose stop`. Stops container but does not remove it -- `bin/ddown`: `docker-compose down`. Stops and destroy a container. +--- ## Front-end framework -We use Bootstrap 5, you can find the documentation here: https://getbootstrap.com/docs/5.2/getting-started/introduction/ +We use Bootstrap 5. Documentation: https://getbootstrap.com/docs/5.2/getting-started/introduction/ ## Finding something to work on diff --git a/db/seeds.rb b/db/seeds.rb index 5b2b6f587..06feefff0 100644 --- a/db/seeds.rb +++ b/db/seeds.rb @@ -15,7 +15,7 @@ Rails.logger.error ' Ubuntu/Debian: apt-get install imagemagick' Rails.logger.error ' Windows: https://imagemagick.org/script/download.php' Rails.logger.error '' - Rails.logger.error 'See native-installation-instructions.md for details.' + Rails.logger.error 'See docs/development-setup.md for details.' Rails.logger.error '=' * 80 exit 1 end diff --git a/docs/coding-agent-setup-skill.md b/docs/coding-agent-setup-skill.md new file mode 100644 index 000000000..e4bda5c7b --- /dev/null +++ b/docs/coding-agent-setup-skill.md @@ -0,0 +1,115 @@ +# Skill: Help a contributor set up codebar planner locally + +Use this skill when a user asks for help setting up the codebar planner application for local development, or when they report errors running the app, tests, or database commands. + +## Context + +The codebar planner is a Rails 8.1 application. Contributors range from junior to senior engineers. The recommended setup path is **native installation** (not Docker). The project uses: + +- **Ruby** (version in `.ruby-version`) managed by **mise** +- **PostgreSQL** as the database +- **ImageMagick** for image processing +- **GitHub OAuth** for authentication (requires a local OAuth app) +- **Bundler** for Ruby dependencies + +## Diagnostic command + +The project has a built-in diagnostic command. Always run this first: + +```bash +bundle exec rake setup:check +``` + +This command checks: +- Ruby version matches `.ruby-version` +- Bundler is installed +- PostgreSQL is installed and accepting connections +- ImageMagick is installed +- `mise.local.toml` exists and contains real GitHub OAuth credentials +- Ruby gems are installed (`bundle check`) +- Database connection works +- Development database exists and is migrated +- Test database exists and is accessible + +**Interpret the output:** +- ✅ = all good, no action needed +- ⚠️ = warning, development can usually proceed but review the note +- ❌ = error, must be fixed before the app will work + +Each error prints a specific fix next to it. Guide the user through those fixes. + +## Common scenarios and responses + +### "I just cloned the repo, what do I do?" + +1. Ask what operating system they are using (macOS or Linux). +2. Run `bundle exec rake setup:check` to see what is already installed. +3. Guide them through the missing pieces using the instructions in `docs/development-setup.md`. +4. Emphasise: they must create a GitHub OAuth app and configure `mise.local.toml` before the app will start. + +### "The app won't start" or "I get an error when running rails server" + +1. Run `bundle exec rake setup:check`. +2. If PostgreSQL errors appear, help them start the service: + - macOS: `brew services start postgresql` + - Linux: `sudo service postgresql start` +3. If GitHub OAuth errors appear, walk them through creating the OAuth app at https://github.com/settings/applications/new and editing `mise.local.toml`. +4. If database errors appear, run `bundle exec rake db:create db:migrate`. +5. If dependency errors appear, run `bundle install`. + +### "Tests fail" + +1. Run `bundle exec rake setup:check` to confirm the test database is accessible. +2. If the test database is missing, run `bundle exec rake db:test:prepare`. +3. Run `bundle exec rspec` to get the failure output. +4. If failures are in JavaScript feature tests, suggest running with `PLAYWRIGHT_HEADLESS=false bundle exec rspec` to see the browser. +5. If failures persist after a clean setup, they may be legitimate bugs — suggest opening an issue. + +### "I can't log in" or "GitHub authentication fails" + +1. Check `mise.local.toml` exists and contains real (not placeholder) values. +2. Verify the GitHub OAuth app callback URL is exactly `http://localhost:3000/auth/github`. +3. Make sure they restarted their terminal after creating `mise.local.toml` so mise loads the variables. +4. Check they are visiting `http://localhost:3000` (not `https` or `127.0.0.1`). + +### "db:seed fails" + +1. Check `bundle exec rake setup:check` for ImageMagick. +2. If ImageMagick is missing, install it: + - macOS: `brew install imagemagick` + - Linux: `apt-get install imagemagick` +3. Re-run `bundle exec rake db:seed`. + +### "I get a 'role does not exist' error from PostgreSQL" + +PostgreSQL does not have a user matching the system username. Help them create it: + +- macOS: `createuser -s $(whoami)` +- Linux: `sudo -u postgres createuser -s $(whoami)` + +Then re-run `bundle exec rake db:create`. + +## Principles + +- **Never recommend Docker** unless the user explicitly asks for it. The project documentation has moved away from Docker as the primary path. +- **Always run `setup:check` first.** It gives concrete, actionable error messages and saves time. +- **Explain the 'why' when juniors ask.** For example, explain that mise manages Ruby versions, that PostgreSQL is the database, and that GitHub OAuth credentials are needed because the app uses GitHub for login. +- **Point to the docs.** `docs/development-setup.md` is the authoritative, detailed guide. Use it as the reference for anything not covered here. +- **Assume the user is not a senior engineer.** Use simple language, avoid jargon without explanation, and break instructions into small steps. + +## Quick reference + +| Problem | First check | Likely fix | +|---------|------------|------------| +| App won't start | `setup:check` | PostgreSQL not running, or missing GitHub credentials | +| Database errors | `setup:check` | `bundle exec rake db:create db:migrate` | +| Tests fail | `setup:check` | `bundle exec rake db:test:prepare` | +| Can't log in | `setup:check` | GitHub OAuth app misconfigured or `mise.local.toml` not loaded | +| Seed fails | `setup:check` | `brew install imagemagick` | +| Missing gems | `setup:check` | `bundle install` | + +## Off-limits + +- Do not modify `.ruby-version` or `Gemfile.lock`. +- Do not commit `mise.local.toml` (it is gitignored, but reinforce this). +- Do not suggest modifying `config/database.yml` unless there is a genuine connection issue that cannot be solved with environment variables. diff --git a/docs/development-setup.md b/docs/development-setup.md new file mode 100644 index 000000000..64e1d7469 --- /dev/null +++ b/docs/development-setup.md @@ -0,0 +1,381 @@ +# Development Setup Guide + +This guide walks you through setting up the codebar planner application on your local machine. It is written for contributors of all experience levels — you do not need to be a senior engineer to follow it. + +**What you will do:** +1. Install the tools the application needs (Ruby, PostgreSQL, etc.) +2. Get the code +3. Configure GitHub login for the app +4. Create the database and install dependencies +5. Start the application and run the tests + +**What this application is:** +A [Ruby on Rails](https://rubyonrails.org/) web application that manages codebar members, workshops, events, and RSVPs. It uses [PostgreSQL](https://www.postgresql.org/) for data storage and [Bootstrap 5](https://getbootstrap.com/) for the front end. + +--- + +## Prerequisites + +You need a computer running **macOS** or **Linux** (including WSL on Windows). The commands below assume a [Unix shell](https://en.wikipedia.org/wiki/Unix_shell) (Terminal on macOS, or any terminal emulator on Linux). + +You will need these tools installed: + +| Tool | What it does | How to check if you have it | +|------|-------------|----------------------------| +| [Git](https://git-scm.com/) | Downloads the code | `git --version` | +| [Homebrew](https://brew.sh/) (macOS) or your distro's package manager (Linux) | Installs other tools | `brew --version` (macOS) | +| [mise](https://mise.jdx.dev/) | Manages Ruby versions and environment variables | `mise --version` | +| [PostgreSQL](https://www.postgresql.org/) | Database server | `psql --version` | +| [ImageMagick](https://imagemagick.org/) | Image processing (used for member avatars) | `convert --version` | + +If any of these are missing, follow the installation instructions below for your operating system. + +--- + +## macOS Setup + +### Step 1: Install Xcode Command Line Tools + +These are free developer tools from Apple. You need them before installing anything else. + +```bash +xcode-select --install +``` + +If a dialog appears, click **Install**. If it says they are already installed, you are good to go. + +### Step 2: Install Homebrew + +Homebrew is a package manager for macOS — it makes installing software much easier. + +```bash +/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)" +``` + +Follow the instructions it prints. After installation, you may need to add Homebrew to your shell path. + +### Step 3: Install mise + +mise manages which version of Ruby this project uses. This is important because different projects need different Ruby versions. + +```bash +brew install mise +``` + +After installing, you need to activate it in your shell. Add this to your shell profile file (`~/.zshrc` if you use the default macOS shell, or `~/.bashrc` if you use Bash): + +```bash +eval "$(mise activate zsh)" +``` + +Then reload your shell: + +```bash +source ~/.zshrc +``` + +### Step 4: Install PostgreSQL + +```bash +brew install postgresql +brew services start postgresql +``` + +`brew services start` makes PostgreSQL run automatically whenever you start your computer. + +By default, PostgreSQL on macOS creates a database user with your computer username and no password. This usually "just works" with Rails applications. + +### Step 5: Install ImageMagick + +```bash +brew install imagemagick +``` + +### Step 6: Install Ruby + +mise reads the `.ruby-version` file in the project and installs the correct version automatically. + +```bash +mise install +``` + +This may take a few minutes. On Apple Silicon (M1/M2/M3/M4) Macs, you may see a compilation warning about `ffi` — this is normal and the installation will still succeed. + +--- + +## Linux Setup + +These instructions are for Debian/Ubuntu-based distributions. If you use a different distribution, use your distribution's equivalent package manager. + +### Step 1: Install system dependencies + +```bash +sudo apt-get update +sudo apt-get install -y git curl build-essential libpq-dev libsqlite3-dev nodejs imagemagick +``` + +`libpq-dev` is required for the Ruby gem that connects to PostgreSQL. + +### Step 2: Install PostgreSQL + +```bash +sudo apt-get install -y postgresql postgresql-contrib +sudo service postgresql start +``` + +You may need to create a PostgreSQL user that matches your Linux username: + +```bash +sudo -u postgres createuser -s $(whoami) +``` + +### Step 3: Install mise + +```bash +curl https://mise.run | sh +``` + +Add mise to your shell profile (`~/.bashrc` or `~/.zshrc`): + +```bash +echo 'eval "$(~/.local/bin/mise activate)"' >> ~/.bashrc +source ~/.bashrc +``` + +### Step 4: Install Ruby + +```bash +mise install +``` + +--- + +## Clone the project + +```bash +# Navigate to where you keep your code projects +cd ~/Documents + +# Clone the repository +git clone https://github.com/codebar/planner.git + +# Enter the project directory +cd planner +``` + +--- + +## Configure GitHub Authentication + +The application uses GitHub OAuth for user login. You need to create a GitHub OAuth application and tell the code about its credentials. + +### 1. Create a GitHub OAuth app + +1. Go to [https://github.com/settings/applications/new](https://github.com/settings/applications/new) +2. Fill in the form: + +| Field | Value | +|-------|-------| +| Application name | `codebar planner local` (or anything memorable) | +| Homepage URL | `http://localhost:3000` | +| Application description | `Local development for codebar planner` | +| Authorization callback URL | `http://localhost:3000/auth/github` | + +3. Click **Register application** +4. You will see a **Client ID** and a **Client Secret**. Keep this page open — you will copy these into the project. + +### 2. Add credentials to the project + +```bash +cp mise.local.toml.example mise.local.toml +``` + +Open `mise.local.toml` in your text editor and replace the placeholder values: + +```toml +[env] +GITHUB_KEY = "your_github_oauth_client_id" +GITHUB_SECRET = "your_github_oauth_client_secret" +``` + +Use the real values from your GitHub OAuth app page. + +**Why this file?** mise automatically loads environment variables from `mise.local.toml`. This keeps secrets out of the code and lets each developer have their own settings. + +**Important:** `mise.local.toml` is ignored by Git, so your credentials will never be accidentally committed. + +--- + +## Install Ruby dependencies + +```bash +gem install bundler +bundle install +``` + +`bundler` is Ruby's dependency manager. It reads `Gemfile` and installs all the Ruby libraries the application needs. + +This step may take a few minutes the first time. + +--- + +## Set up the database + +```bash +bundle exec rake db:create db:migrate db:test:prepare +``` + +This command does three things: +- `db:create` — creates the development and test databases in PostgreSQL +- `db:migrate` — runs database migrations (sets up tables, columns, indexes) +- `db:test:prepare` — makes sure the test database is ready for running tests + +--- + +## Run the diagnostic check + +We provide a built-in command that checks your environment and tells you if anything is missing: + +```bash +bundle exec rake setup:check +``` + +If this prints all green checkmarks, you are ready to go. If it reports any errors, follow the suggestions it prints. + +--- + +## Start the application + +```bash +bundle exec rails server +``` + +You will see output ending with something like: + +``` +=> Booting Puma +=> Rails 8.1.2 application starting in development +=> Run `bin/rails server --help` for more startup options + Please visit https://localhost:3000 +``` + +Open [http://localhost:3000](http://localhost:3000) in your web browser. + +**To stop the server**, press `Ctrl + C` in the terminal. + +--- + +## Run the tests + +```bash +bundle exec rspec +``` + +This runs the full test suite. It should take a few minutes and report something like: + +``` +1000+ examples, 0 failures +``` + +If you see any failures, please check that your setup matches this guide, then ask in the [codebar Slack](https://slack.codebar.io). + +### Run a single test file + +```bash +bundle exec rspec spec/models/member_spec.rb +``` + +### Run a specific test + +```bash +bundle exec rspec spec/models/member_spec.rb:42 +``` + +### Run tests in parallel (faster) + +```bash +bundle exec parallel_rspec spec/ -n 3 +``` + +### Run JavaScript-enabled feature tests with a visible browser + +Some tests use a headless browser. To see the browser: + +```bash +PLAYWRIGHT_HEADLESS=false bundle exec rspec +``` + +--- + +## Optional: Add sample data + +To populate the database with fake workshops, members, and events for local testing: + +```bash +bundle exec rake db:seed +``` + +--- + +## Make yourself an admin + +After signing up in your local app, you can give yourself admin privileges: + +```bash +bundle exec rails runner "Member.find_by(email: 'your-email@example.com').add_role(:admin)" +``` + +Replace `your-email@example.com` with the email you used when signing up locally. + +--- + +## Common problems + +### "psql: command not found" + +PostgreSQL is not installed or not in your PATH. Reinstall it and make sure your terminal is restarted after installation. + +### "Could not connect to server: Connection refused" + +PostgreSQL is not running. Start it: +- macOS: `brew services start postgresql` +- Linux: `sudo service postgresql start` + +### "FATAL: database 'planner_development' does not exist" + +Run `bundle exec rake db:create db:migrate`. + +### "Bundler::GemNotFound" or "Could not find gem" + +Run `bundle install` again. + +### "role does not exist" when creating the database + +PostgreSQL does not have a user matching your computer username. Create it: + +```bash +# macOS (usually not needed) +createuser -s $(whoami) + +# Linux +sudo -u postgres createuser -s $(whoami) +``` + +### GitHub login fails with "missing credentials" + +Check that `mise.local.toml` exists and contains real values (not the placeholders). Then restart your terminal so mise loads the new variables. + +--- + +## Need help? + +- [codebar Slack](https://slack.codebar.io) — the #planner channel is the best place to ask +- [GitHub issues](https://github.com/codebar/planner/issues) — for bugs or improvements to this guide + +--- + +## Docker (not recommended for most contributors) + +A Docker setup exists in this repository, but it is **not the recommended path** for local development. It is slower, harder to debug, and does not support running JavaScript feature tests with a visible browser. + +If you still prefer Docker, see the Docker commands in `bin/d*`. However, the instructions above are the supported and recommended path. diff --git a/lib/tasks/setup.rake b/lib/tasks/setup.rake new file mode 100644 index 000000000..8103c36d5 --- /dev/null +++ b/lib/tasks/setup.rake @@ -0,0 +1,236 @@ +# frozen_string_literal: true + +namespace :setup do + desc 'Inspect your local development environment and report what is missing or misconfigured' + task check: :environment do + checker = SetupChecker.new + checker.run + exit(checker.all_ok? ? 0 : 1) + end + + class SetupChecker + CHECKS = [ + :check_ruby_version, + :check_bundler, + :check_mise, + :check_postgresql, + :check_imagemagick, + :check_github_credentials, + :check_bundle, + :check_database_connection, + :check_database_exists, + :check_database_migrated, + :check_test_database + ].freeze + + def initialize + @results = [] + @expected_ruby = File.read('.ruby-version').strip + end + + def run + puts + puts '== codebar planner setup check ==' + puts + puts 'This command inspects your local development environment and reports' + puts 'anything that needs attention before you can run the application.' + puts + + CHECKS.each { |check| send(check) } + + print_summary + end + + def all_ok? + @results.none? { |r| r[:status] == :error } + end + + private + + def ok(title, message) + @results << { status: :ok, title:, message: } + puts " ✅ #{title}: #{message}" + end + + def warn(title, message, fix) + @results << { status: :warn, title:, message:, fix: } + puts " ⚠️ #{title}: #{message}" + puts " → #{fix}" + end + + def error(title, message, fix) + @results << { status: :error, title:, message:, fix: } + puts " ❌ #{title}: #{message}" + puts " → #{fix}" + end + + def check_ruby_version + current = RUBY_VERSION + if current == @expected_ruby + ok('Ruby version', "#{current} (matches .ruby-version)") + else + error('Ruby version', "#{current} (expected #{@expected_ruby})", + "Install Ruby #{@expected_ruby}. See docs/development-setup.md for options.") + end + end + + def check_bundler + if system('which bundle > /dev/null 2>&1') + ok('Bundler', 'installed') + else + error('Bundler', 'not found', + 'Run: gem install bundler') + end + end + + def check_mise + if system('which mise > /dev/null 2>&1') + ok('mise', 'installed') + else + warn('mise', 'not found', + 'Optional but recommended. Install: brew install mise (macOS) or see https://mise.jdx.dev') + end + end + + def check_postgresql + if !system('which psql > /dev/null 2>&1') + error('PostgreSQL', 'psql not found', + 'Install: brew install postgresql && brew services start postgresql (macOS) or see docs/development-setup.md') + return + end + + # Check if postgres is accepting connections + db_config = ActiveRecord::Base.connection_db_config.configuration_hash + host = db_config[:host] || 'localhost' + port = db_config[:port] || 5432 + user = db_config[:username] || ENV['USER'] + password = db_config[:password] + + env = password ? { 'PGPASSWORD' => password } : {} + cmd = "PGPASSWORD=#{password} psql -h #{host} -p #{port} -U #{user} -c 'SELECT 1' > /dev/null 2>&1" + if system(env, cmd) + ok('PostgreSQL', "running and accepting connections on #{host}:#{port}") + else + error('PostgreSQL', "not accepting connections on #{host}:#{port}", + 'Start PostgreSQL: brew services start postgresql (macOS). Check credentials in config/database.yml or env vars.') + end + end + + def check_imagemagick + if system('which convert > /dev/null 2>&1') + ok('ImageMagick', 'installed') + else + error('ImageMagick', 'not found (convert command missing)', + 'Install: brew install imagemagick (macOS) or see docs/development-setup.md') + end + end + + def check_github_credentials + if !File.exist?('mise.local.toml') + error('GitHub OAuth', 'mise.local.toml not found', + 'Copy: cp mise.local.toml.example mise.local.toml, then edit with your GitHub app credentials.') + return + end + + content = File.read('mise.local.toml') + if content.include?('your_github_oauth') || content.include?('your_') || content.include?('fill_in') + error('GitHub OAuth', 'mise.local.toml contains placeholder values', + 'Edit mise.local.toml with real GITHUB_KEY and GITHUB_SECRET from your GitHub OAuth app.') + else + ok('GitHub OAuth', 'mise.local.toml configured') + end + end + + def check_bundle + if system('bundle check > /dev/null 2>&1') + ok('Ruby dependencies', 'all gems installed') + else + error('Ruby dependencies', 'missing gems', + 'Run: bundle install') + end + end + + def check_database_connection + begin + ActiveRecord::Base.connection.execute('SELECT 1') + ok('Database connection', 'can connect to PostgreSQL') + rescue StandardError => e + error('Database connection', "cannot connect (#{e.class}: #{e.message})", + 'Check PostgreSQL is running and credentials in config/database.yml are correct.') + end + end + + def check_database_exists + begin + ActiveRecord::Base.connection.execute('SELECT 1') + if ActiveRecord::Base.connection.execute("SELECT 1 FROM pg_database WHERE datname = 'planner_development'").any? + ok('Development database', 'planner_development exists') + else + error('Development database', 'planner_development does not exist', + 'Run: bundle exec rake db:create') + end + rescue StandardError => e + error('Development database', "cannot check (#{e.class}: #{e.message})", + 'Run: bundle exec rake db:create') + end + end + + def check_database_migrated + begin + if ActiveRecord::Base.connection.execute("SELECT 1 FROM schema_migrations LIMIT 1") + latest = ActiveRecord::Base.connection.execute( + "SELECT version FROM schema_migrations ORDER BY version DESC LIMIT 1" + ).first + if latest + ok('Database migrations', "up to date (latest: #{latest['version']})") + else + error('Database migrations', 'no migrations found', + 'Run: bundle exec rake db:migrate') + end + end + rescue StandardError => e + error('Database migrations', "cannot check (#{e.class}: #{e.message})", + 'Run: bundle exec rake db:migrate') + end + end + + def check_test_database + db_config = Rails.configuration.database_configuration['test'] + host = db_config['host'] || 'localhost' + port = db_config['port'] || 5432 + user = db_config['username'] || ENV['USER'] + password = db_config['password'] + database = db_config['database'] + + env = password ? { 'PGPASSWORD' => password } : {} + cmd = "PGPASSWORD=#{password} psql -h #{host} -p #{port} -U #{user} -c 'SELECT 1' #{database} > /dev/null 2>&1" + if system(env, cmd) + ok('Test database', "#{database} exists and is accessible") + else + error('Test database', "#{database} missing or not accessible", + 'Run: bundle exec rake db:test:prepare') + end + end + + def print_summary + puts + errors = @results.count { |r| r[:status] == :error } + warnings = @results.count { |r| r[:status] == :warn } + ok_count = @results.count { |r| r[:status] == :ok } + + if errors.zero? && warnings.zero? + puts "✅ All checks passed! Your environment is ready for development." + puts + puts "Next steps:" + puts " bundle exec rails server # Start the app" + puts " bundle exec rspec # Run the test suite" + puts " bundle exec rake db:seed # (Optional) Add sample data" + elsif errors.zero? + puts "⚠️ #{warnings} warning(s). You can probably start developing, but review the warnings above." + else + puts "❌ #{errors} error(s) and #{warnings} warning(s) need attention before you can start developing." + end + puts + end + end +end diff --git a/native-installation-instructions.md b/native-installation-instructions.md deleted file mode 100644 index d4f4b6bbf..000000000 --- a/native-installation-instructions.md +++ /dev/null @@ -1,101 +0,0 @@ -# Installing Ruby/Postgres on your local environment - -These are the original instructions for natively installing the app to your machine, using local installations of Ruby and Postgres. For most people, we recommend [using Docker instead](README.md). - -## Contents -1. [Set up a Ruby Environment](#set-up-a-ruby-environment) - - Option 1: Using rvm - - Option 2: Using rbenv and ruby-build -2. [Install and run PostgreSQL](#install-and-run-postgresql) - - Using Homebrew on a Mac -3. [Set up the database](#set-up-the-database) - - Generate sample data -4. [Run the app](#run-the-app) -5. [Run the tests](#run-the-tests) -6. (Optional) Note that to be able to use the page as an admin, you must first give yourself admin privileges. Make sure you have started your app and signed up as an user on your locally running app. Then run this on command line: `rails runner "Member.find_by(email: '').add_role(:admin)"`. - -## Set up a Ruby Environment - -You will need to install Ruby using RVM or rbenv. - -### Option 1: Using [rvm](https://rvm.io/rvm/install) - -```bash -CPPFLAGS=-DUSE_FFI_CLOSURE_ALLOC rvm install 3.4.8 -``` -We need to set the CPPFLAGS env variable to be able to install Ruby 3.4.8 on M1 Mac machines. See more: [https://github.com/ffi/ffi/issues/869#issuecomment-1233000037](https://github.com/ffi/ffi/issues/869#issuecomment-1233000037) - -### Option 2: Using [rbenv](https://github.com/sstephenson/rbenv) and [ruby-build](https://github.com/sstephenson/ruby-build) - -```bash -rbenv install 3.4.8 -rbenv global 3.4.8 -``` - -## Install and run PostgreSQL - -[The PostgreSQL Wiki has detailed installation guides](https://wiki.postgresql.org/wiki/Detailed_installation_guides) for various platforms, but probably the simplest and most common method for Mac users is with Homebrew: - -### Using [Homebrew](https://brew.sh/) on a Mac - -Note: You might need to install another build of Xcode Tools (typing `brew update` in the terminal will prompt you to update the Xcode build tools). - -Install Postgres: -```bash -brew update -brew install postgresql -brew services start postgresql -``` - -Install required dependencies: -``` -brew install imagemagick -``` - -Install the Gems: -```bash -gem install bundler -bundle config without production -bundle install -``` - -## Set up the Database - -Adjust `config/database.yml` as needed. - -```bash -bundle exec rake db:create -bundle exec rake db:migrate db:test:prepare -``` - -*Note:* If you are running OSX Yosemite, you may experience a problem connecting to -Postgres. [This stackoverflow answer](http://stackoverflow.com/a/26458194/1510063) might help. - -### Generate sample data - -```bash -bundle exec rake db:seed -``` - -## Run the app - -```bash -bundle exec rails server -``` - -### Run the tests - -```bash -bundle exec rake -``` - -## Setting up a local admin user - -- To assign admin permissions to a local user run the below commands using the member's email address. -- Note that a member is effectively a user. - -```bash -rails c -user = Member.find_by(email: 'test@example.com') -user.add_role :admin -```