PlaceCal
A combination of technology, community development and public sector strategy designed to help people bring their community together by aggregating information about community groups and events.
🅰️ℹ️ Imagine a platform that unites your community by effortlessly bringing together information about local groups, events, and activities. Your mission is to develop "PlaceCal," a dynamic tool that aggregates and showcases community resources, fostering connection and engagement among residents. Consider how technology can bridge gaps, making it easier for everyone to discover and participate in community initiatives—whether it's a local book club, volunteer opportunities, or neighborhood festivals. Focus on creating an inclusive experience that empowers users to contribute their own events and groups, ensuring no one is left out. Leverage your creativity to design a solution that not only functions smoothly but also resonates with diverse community members. How can you ensure that the platform is accessible and user-friendly for all ages and backgrounds? Emphasize collaboration and transparency in your approach, and remember that every idea counts. Together, let's create a vibrant community hub that encourages connection, participation, and joy!
PlaceCal
Introduction
PlaceCal is an online calendar which lists events and activities by and for members of local communities, curated around interests and locality.
The codebase doesn't currently have enough seeds to create a dev environment suitable for developing from scratch. If you're interested in contributing to PlaceCal please get in touch at [email protected]
To get an idea of the project and what we're about, check out the handbook.
Requirements
To run PlaceCal locally you will need to install the following dependencies:
- Docker
- Ruby 3.3.4
- Node.js 20.x & (optional) nvm to manage it
- Yarn 1.x
- ImageMagick for image manipulation
- Graphviz for documentation diagrams
- Chrome/Chromium for system tests along with a matching version of Chromedriver
Quickstart with docker for GFSC devs
Make sure all of the above dependencies are installed (and ask someone to add your public ssh key to the servers if you are staff).
Then make sure the docker daemon is running, and run
make setup_with_docker
Local site is now running at lvh.me:3000
Some other useful commands for developing can be found in the makefile.
Troubleshooting
If the make command fails and you can't work out why, here are some suggestions:
- Do you have an older version of the database hanging around? Try running
rails db:drop:all
- Is the docker daemon running?
- Is the port in use by another application or docker container? Try stopping or removing any conflicting containers
- Are you using the correct node version? Try running
nvm use
Quickstart for everyone else
Set up Postgresql locally with docker
If you don't already have Postgresql installed and running, you can set it up with docker, just run make docker
. To tear down the docker setup, run make clean
.
Run the setup script
bin/setup
Amongst other things, this will create an admin user for you:
- Username:
[email protected]
- Password:
password
Run the thing
- Start the server with
bin/dev
- Make sure you use
lvh.me:3000
instead oflocalhost:3000
or you will have authentication problems - The admin interface is at
admin.lvh.me:3000
- Access code docs through your local filesystem and update them with
bin/rails yard
Importing calendars
To import all events, run the following command.
rails events:import_all_calendars
After this has run once, the following command can be run which attempts to skip calendars which have not been updated. This should be run regularly on a cron in production environments. If you are using dokku to deploy like we are, this is handled in the app.json
config file.
rails events:scan_for_calendars_needing_import
To import one calendar, run:
rails events:import_calendar[100]
# nb: zsh users will need to escape brackets
rails events:import_calendar\[100\]
Testing, linting and formatting
PlaceCal tests are written in minitest. We use Rubocop to lint our Ruby code.
We use Prettier to format everything it's able to parse. We run this automatically as part of a pre-commit hook.
You can run the tests & rubocop with:
make test
Documentation
Further documentation for PlaceCal is in the PlaceCal Handbook.
The developer Procfile will load a yard
language server, this is visible at http://localhost:8808
.
If you are working with the code and are completely lost you can also try the GFSC discord server where you can prod a human for answers.
Generating new components
We use view_component to make components, and you can create a new one by running rails g component <Name> <args>
Previously this system used mountain view, and some of the components are still generated using this.
More info here: https://viewcomponent.org/guide/generators.html
API
API examples and test environment are provided using Bruno.
Install it with your system package manager then point it at the collections
directory.
Donations
If you'd like to support development, please consider sending us a one-off or regular donation on Ko-fi. You can do this through the "support" button in GitHub at the top of this repo.
Previous
The Tech We Want