Gather

The App for Community - https://info.gather.coop

Platform

Ruby on Rails applications are best developed and run on Linux, Unix, or Mac OS. Development is also possible, though not recommended, on Windows. See the Rails website for more information.

Gather is a Ruby on Rails application with some client-side JavaScript for dynamic view elements. HTML is rendered server-side. SCSS is used for styling.

Development is supported on Linux and macOS. Windows is not supported.

Quick Start

Using Dev Container (Recommended)

The easiest way to get started is with VS Code and Dev Containers:

1. Install Docker and VS Code
2. Install the Dev Containers extension
3. Clone and open the project:

   git clone https://github.com/gather-community/gather.git
   code gather

4. When prompted, click "Reopen in Container" (or run Dev Containers: Reopen in Container from the command palette)
5. Once the container is built, run:

   mise setup

Manual Setup

If not using Dev Containers:

git clone https://github.com/gather-community/gather.git
cd gather
git checkout develop
mise setup

The setup script will guide you through:

• Checking dependencies
• Generating configuration files
• Starting data services (PostgreSQL, Redis, Elasticsearch)
• Provisioning the database with an admin user
• Installing SSL certificates

Once complete, start the application:

bin/dev           # Start Rails server with foreman
bin/delayed_job run  # Start background job processor (separate terminal)

Then visit https://gatherdev.org:3000 and sign in with the credentials shown during setup.

System Dependencies

We recommend using mise for managing tool versions and running configuration tasks. The project includes a mise.toml that installs Ruby, Node.js, and other required tools automatically.

Required Tools

Tool	Purpose
Ruby (see .ruby-version)	Application runtime
Node.js (see .nvmrc)	JavaScript tooling
libvips 8.8+	Image processing

Optional Tools

Tool	Purpose
Docker	Only required if using the repo's compose.yml for data services
Mailcatcher	Email testing (gem install mailcatcher)
Mailman 3	Mailing list integration (see below)

Setup Stages

Run individual setup stages with:

mise deps    # Check dependencies
mise conf    # Generate configuration
mise data    # Setup data services and database
mise ssl     # Configure SSL certificates

The mise data stage will create an admin user for development. If you need to reset the admin password later, run mise data again and select "Reset super admin password".

Running the Application

1. Start data services (PostgreSQL, Redis, Elasticsearch):

   docker compose up -d

   If you're using your own data services, ensure they're running and configured in config/database.yml and config/settings.local.yml. The mise data task will attempt to start Docker Compose services if it can't connect to the configured hosts.

2. Run tests to verify everything is working:

   bundle exec rspec

3. Start the application:

   bin/dev           # Start Rails server with foreman
   bin/delayed_job run  # Start background job processor (separate terminal)

   Job logs go to log/development.log. The log/delayed_job.log file contains only initialization and job state information.

Rails Console

When using the Rails console, set a tenant first:

CH.tenant(1)  # Use Community ID 1

Caching

Caching is off by default in development. Enable temporarily with:

CACHE=1 rails server

Linters

We use eslint, rubocop, and scss_lint. The CI system enforces these—PRs won't be approved until issues are resolved.

Troubleshooting

Elasticsearch 403 Errors

Reset the index:

rails console -e development
Work::Shift.__elasticsearch__.create_index!(force: true)

To re-populate after resetting:

ActsAsTenant.current_tenant = Cluster.find(...)
Work::Shift.find_each { |s| s.__elasticsearch__.index_document }

Mailman 3 Setup

Only required if working on mailing list integration.

Mailman runs as two Docker containers (mailman-core and mailman-web) included in docker-compose.yml. Running mise data (or docker compose up -d) starts them alongside the other services. A Postorius admin account is created automatically with username admin and password gather-mailman-dev.

Inspecting list state (Postorius web UI)

Visit http://localhost:8000/postorius/ and log in with the superuser you created above. From here you can browse domains, lists, and memberships.

Inspecting list state (REST API)

All REST API calls use HTTP Basic auth with restadmin / restpass. Run these from inside the devcontainer (use mailman-core as the hostname). From your host Mac terminal, replace mailman-core with localhost.

# List all mailing lists
curl -u restadmin:restpass http://mailman-core:8001/3.1/lists

# Show a specific list (replace list@domain with the actual address)
curl -u restadmin:restpass http://mailman-core:8001/3.1/lists/list@domain

# Show all members of a list
curl -u restadmin:restpass "http://mailman-core:8001/3.1/lists/list@domain/roster/member?count=100&page=1"

# Show nonmembers (allowed senders) of a list
curl -u restadmin:restpass "http://mailman-core:8001/3.1/lists/list@domain/roster/nonmember?count=100&page=1"

# Show a specific membership by ID
curl -u restadmin:restpass http://mailman-core:8001/3.1/members/MEMBER_ID

Making modifications (REST API)

# Add a member to a list
curl -u restadmin:restpass -X POST http://mailman-core:8001/3.1/members \
  -d "list_id=list.domain&subscriber=user@example.com&role=member&pre_verified=true&pre_confirmed=true&pre_approved=true"

# Update a membership (e.g. set moderation_action to accept)
curl -u restadmin:restpass -X PATCH http://mailman-core:8001/3.1/members/MEMBER_ID \
  -d "moderation_action=accept"

# Delete a membership
curl -u restadmin:restpass -X DELETE http://mailman-core:8001/3.1/members/MEMBER_ID

# Update list settings
curl -u restadmin:restpass -X PATCH http://mailman-core:8001/3.1/lists/list@domain/config \
  -d "advertised=false"

Viewing logs

docker logs mailman-core        # Mailman core logs (REST API, delivery, errors)
docker logs mailman-web         # Postorius web UI logs
docker logs -f mailman-core     # Follow logs in real time

Dropping into a shell

docker exec -it mailman-core bash

VS Code

When using Dev Containers, extensions and settings are installed and configured automatically.

If working locally without a Dev Container, install these recommended extensions:

Ruby/Rails:

• Shopify.ruby-lsp - Ruby language server
• Shopify.ruby-extensions-pack - Ruby extensions pack
• KoichiSasada.vscode-rdbg - Ruby debugger
• rubocop.vscode-rubocop - RuboCop linting
• aliariff.vscode-erb-beautify - ERB formatting

JavaScript/TypeScript:

• dbaeumer.vscode-eslint - ESLint
• esbenp.prettier-vscode - Prettier formatting
• marcoroth.stimulus-lsp - Stimulus (Hotwire) support
• bradlc.vscode-tailwindcss - Tailwind CSS

Utilities:

• hverlin.mise-vscode - mise integration
• ckolkman.vscode-postgres - PostgreSQL client
• ms-azuretools.vscode-docker - Docker support
• foxundermoon.shell-format - Shell script formatting
• timonwong.shellcheck - Shell script linting
• EditorConfig.EditorConfig - EditorConfig support

Recommended settings (.vscode/settings.json):

{
  "editor.tabSize": 2,
  "editor.formatOnSave": true,
  "editor.defaultFormatter": "esbenp.prettier-vscode",
  "[ruby]": {
    "editor.defaultFormatter": "Shopify.ruby-lsp"
  },
  "[erb]": {
    "editor.defaultFormatter": "aliariff.vscode-erb-beautify"
  },
  "[shellscript]": {
    "editor.defaultFormatter": "foxundermoon.shell-format"
  },
  "files.associations": {
    "*.html.erb": "erb"
  }
}

Acknowledgements

This project is happily tested with BrowserStack!