shift-org/shift-docs

Shift2Bikes: website and calendar for shift and pedalpalooza

Overview

The purpose of the Shift/Pedalpalooza Calendar is to empower citizens to create and view bike events and to spread bike fun.

You can see the production site here: https://www.shift2bikes.org

Software

The calendar is split into two main parts: a frontend, and a backend. The frontend is what most people think of the as the Shift website: it includes all of the webpages and static content. The backend holds all of the user submitted rides, and sends emails to users when they create new rides.

The frontend uses:

• Hugo, using:
  • the theme "s2b_hugo_theme", ported from the "Universal" theme
  • the content from the legacy Shift website
• Netlify web hosting to serve the content
  • the Netlify CMS for editing static pages in Markdown

The backend uses:

• Docker
• Nginx
• MySQL
• Node.js, and a variety of npm modules.

Contributing

• If you want to change something about the site configuration or theme, pull requests are welcome. Once you create a PR, you can immediately check out a link to the build status, log, and a preview of your changes.
• If you only want to edit CONTENT rather than any code or site styling, (including creating new pages), this doc shows how to easily do so without writing code.

Frontend development with Netlify

While creating a pull request does automatically deploy a preview of the frontend to Netlify, you can also create previews manually: this could help you do things like theme development in your own repository before submitting your pr.

1. fork repo
2. read the comments in the netlify.toml file around changing the build command in the [context.production] section and make changes if needed.
3. deploy on Netlify by linking your forked repo. Included configuration file netlify.toml should mean 0 additional configuration required to get the site running. If you get a build failure around access denied for ssh, you probably need the advice in step 2 just above this!

If you have trouble with it please file an issue to let us know what you tried and what happened when you did.

Local development with Docker

The production backend is run in several docker containers; including nginx, mysql, and the node server.

The docker configuration also supports running your own frontend and backend server locally. The following steps assume a Linux, or MacOs development environment. On Windows, you'll need something like the Windows Subsystem for Linux.

1. Install Docker: https://docs.docker.com/get-docker/
2. Download source code: git clone https://github.com/shift-org/shift-docs.git
3. Start shift site: cd shift-docs ; ./shift up
4. If you're standing up the site for the first time, add database tables with the setup script: ./shift mysql-pipe < services/db/seed/setup.sql.
5. Visit https://localhost:4443/ . If this leads to an SSL error in chrome, you may try flipping this flag: chrome://flags/#allow-insecure-localhost

Note that no changes to the filesystems inside the container should ever be needed; they read from your local filesystem so updating the local FS will show up in the container (perhaps after a restart). Updating, changing branches, etc can be done with git commands outside of the container (git checkout otherbranch or git pull).

So - now you can hopefully access the site. But a real end-toend test of yoursetup, would be creating an event:

1. visit https://localhost:4443/addevent/
2. fill out all required fields (ones marked with an asterisk), for a date a day or two in the future.
3. save the event (fix any validation errors around missing fields to ensure it saves)
4. In production, we send you an email with a link to confirm the ride listing; we also write a copy of that email to the file services/node/shift-mail.log. For local development, we don't actually send the email, so get the confirmation link from that mail log, visit it, and hit publish event
5. hopefully see your event on the https://localhost:4443/calendar page!

Important Project Files

• docker-compose.yml

  • docker container settings
  • The defined containers (db, nginx, etc) become pingable host names from the other running containers. For example, attached to the nginx container, you can "ping db"
  • Contains the container specific mappings between host and docker container persistent volumes.

• shift

  • This is the convenience wrapper that sets up the environment and has various convenience sub-commands to connect to the environment and manipulate it as well. This is how you'll start the project, connect to the database, etc!
  • contains environment variables that get loaded and are then available for docker to import. Docker environment variables that will be important are defined separately for each container (see: docker-compose.yml). Run env inside an attached docker container to see the variables that made it into the running container.

• secrets and secrets.override

  • these are the credentials to connect to your local instance. You should change them if you host your site allowing public connections!

• shift.overrides and shift.overrides.production

  • these are the local (potential) configuration overrides, that aren't secret

Shift subcommands of interest

• ./shift attach node
  • node is a reference to the named docker container. Note that you want just nginx, db or node not the full image name (shift_nginx_1)
  • Attaches to the running docker container in the shift stack
• ./shift up
  • If necessary, first builds, and then starts up the docker containers (will also restart if run while the environment is already running.)
• ./shift logs nginx
  • Will start tailing the logs for the specified container (nginx in this case)
  • multiple container names can be mentioned
• ./shift down
  • stops the docker containers

Docker Daemon commands of interest

• docker ps
  • lists all of the running process and port information from docker (ex: you can see the postgres service port)
• docker volume ls
  • This will show the persistent volumes that docker knows about. The shift project volumes are prefixed with shift_
  • The "shift_" docker namespace comes from the shift file: export COMPOSE_PROJECT_NAME="shift"

Local development with Node.js

You can also do local development with node. These steps will setup a local node server which, by default, acts as both frontend and backend.

After cloning the repo, install node (currently Node.js v20). Then, open a command prompt or terminal window, change to some useful directory for development, and do the following:

1. cd shift-docs
2. npm install
3. optionally, create some placeholder events with: npm run -w tools make-fake-events
4. npm run dev
5. browse to http://localhost:3080, and you should see the site running locally.

When you new create events, the link for activating those events will be written to the terminal. ( In this mode, Sqlite is used instead of MySQL. )

Node tests

If you are writing javascript code in the node backend, you can test everything is working as expected using npm test.

Local previews using production data

As an alternative to npm run dev, you can preview a local frontend with the actual production backend by using: npm run -w tools preview.

NOTE: any events you create while previewing this way will be seen by the world!

Ethereal email

Before executing npm run dev, you can configure email debugging using npm run -w tools new-ethereal-cfg. It will generate a shift-email.cfg file in your bin directory which will be used when adding new events. Use the username and password listed in that file to check for emails here: https://ethereal.email/login.

No actual emails are sent when running this way.

shift-docs's Issues

update pedalpalooza content on calendar (per request from Meghan S)

The following are requests from the social and pedalpalooza planning teams. These are changes needed to the new calendar/fun-view rather than the legacy site. They were communicated via email thread a few weeks ago to Josh and I, but not added here in a place where the team could see them, so here we go:

1. Add 2018 to the Archive: http://www.shift2bikes.org/fun2/pedalpaloozaArchive
2. Update the 2017 image to the 2017 image, not the 2018 here: http://www.shift2bikes.org/cal/viewpp2017.php (done)
3. Make a new landing page for 2019 "classic cal" view. Here's the 2018 one: http://shift2bikes.org/cal/viewpp2018.php (won't fix, since this is a legacy page.)
4. Replace the banner image on http://www.shift2bikes.org/fun2/pedalpalooza with this image until we have a 2019 image: https://drive.google.com/file/d/1MejV45nLapnjoAps6I9ArD7BGkrrDJ-X/view?usp=sharing
5. Remove the card images beneath the Paypal Donate button so it just says "Donate" here: http://www.shift2bikes.org/fun2/pedalpalooza
6. Update http://www.shift2bikes.org/fun2/pedalpalooza to have 2019 language. Below is the requested update:

---

Pedalpalooza!

About

Pedalpalooza is a month of bikey fun. With hundreds of different events, most organized by individuals, bikers of all persuasions are likely to find many events of interest. Nearly all events are free.

Add your events for 2019 now! Seeking inspiration? View the Pedalpalooza archives of past bike fun events. If you need help creating or editing an event, contact the calendar crew

Donate

calendar: Replace raster icons with SVGs

SVGs are resolution independent and will look good on any screen at any zoom level. They can also inherit CSS colors so they are more easily adapted and re-used. There are some accessibility advantages as well (such as automatic re-coloring in Windows High Contrast mode, whereas PNG icons won't). Lastly, the visual style of the existing icons is a bit inconsistent, so a visual refresh would be nice.

Some of the calendar icons have already been done (location pin, organizer, expand/collapse arrow) but there are still more to do (start time, website, etc.).

fix 404 page for netlify

need to route netlify's static/404.html to our "real, editable by CMS 404 page" in content/pages/404.md

fix outgoing emails

Sometime in the past week email from api.shift2bikes.org stopped working. Need to diagnose and fix

calendar: ability to go back in time

Overview

There's no good way to scroll back a few days from today, or to go directly back to a prior time period outside of an old pedalpalooza archive.

Requested by

Requested by community members Johnny and Meghan

content: Review http://old.shift2bikes.org/allbike.php to see if any of that info needs to come over

Should probably work with the communications committee on this. In there we have:

• static assets: (fool wants these): logos, http://old.shift2bikes.org/images/pp/Pedalpalooza_Ride_Recaps_2008.pdf, http://old.shift2bikes.org/images/bikefun/xmasbikecarols.pdf, stickers
• bonb, mcbf, safety/educational, old meeting minutes, bike rack rental, calendar info (already migrated)
• [ ] visitor info?
• ride leader primer (http://old.shift2bikes.org/allbike.php#Ride_Leader_Primer) should check for incorporating into lead-a-social-ride page
• wnbr (moved to their website)
• ride recap form (should turn it into a webform if we do migrate it)

calendar: front-end event params are off by one day

Follows #132.

Steps:

1. Navigate to https://www.shift2bikes.org/calendar/?startdate=2018-01-01

Result:
List of events is returned, but starting with 2017-12-31 instead of 2018-01-01.

Notes:
I traced through this for a while and had trouble making heads or tails of it, but it seems to be rooted in some non-intuitive Javascript time zone nonsense.

content: paypal donate button could be on a few more pages

not every page. but maybe 3 more.

calendar: Add Event - choosing Cancel > Discard Event doesn't do anything

1. Navigate to Calendar > Add Event
2. Choose Cancel button
3. In the confirmation prompt, choose Discard Event

Result: The confirmation prompt is dismissed, but otherwise nothing happens.

We could either:

• Make "Discard Event" redirect to the regular Calendar page.
• Just get rid of the Cancel button. People can just abandon the page if they want to discard an in-progress submission.

calendar: create iCalendar feed for "all future event data"

Overview

We got so involved in remaking the web calendar that we forgot that most people would rather use their own calendar (usually google or apple calendars) :P. Supporting this standard should give us both: https://en.wikipedia.org/wiki/ICalendar

We have fixed the pedalpalooza ical feed in early June 2021, and just need to port this to a "general calendar" version now!

Related

Might be able to reuse some code from RSS implementation: #61 or the legacy codebase that had this: Shift2Bikes/shiftcal@b053a31

Requested by:

Requested by community member Johnny. fool would like it too, and at pedalpalooza time it would be cool++;

update TODO to current (most of that old stuff is not valid)

it's ok if it's empty, just needs to not have legacy

remove dates from (almost all) frontmatter

we don't need to show last updated on anything except the playbooks, IMNSHO. If we do this we will also have to:

• reconfigure the CMS to not require the date field,
• and make sure hugo doesn't barf if we take it out.

The "RISEUP" link in the navbar should make it more obvious that you are leaving the site

Since the Riseup link in the navbar causes you to leave the shift2bikes site, it seems like it should be the last item in the bar and maybe be a different color. Otherwise it is somewhat unexpected when you click it and navigate away from the site. It may be a good idea to make it a target=_blank link as well so it opens in a new tab.

sync netlify.toml settings with UI

from netlify build logs. fool can sync these up here: https://app.netlify.com/sites/shift-docs/settings/deploys

2:10:34 PM: Different publish path detected, going to use the one specified in the toml file: 'site/public/' versus 'public' in the site
2:10:35 PM: Different build command detected, going to use the one specified in the toml file: 'hugo' versus 'mkdir public && hugo' in the site
2:10:35 PM: Different base path detected, going to use the one specified in the toml file: 'site/' versus '' in the site

calendar: including a large image will cause event submission to fail with server error

Reproduction steps:

1. create an event, leave all defaults
2. add required fields (event name, details, select a date, venue, address, check "I've read the comic box,
3. add the attached image
4. submit event (see popup and hit ok)
5. notice no email about event being created & no event created

cc @sdobz

Static pages for Pedalpalooza archives 2002–2007

Pedalpalooza 2008 and later are in the database; 2007 and earlier are just static pages on the old site. We need to scrape the data from the old static pages for those years and just make static content pages.

calendar: provide RSS feed for various time windows

This is a feature request.

We can see from stats last year that the RSS feeds for the next week and tomorrow were pretty popular:

• http://shift2bikes.org/cal/viewrssweek.php had >23k views over 2018
• /cal/viewrsstomorrow.php had >7k views over 2018
• /cal/viewrss.php had >6k views over 2018

So...I think it was loved and is used :)

calendar: "send email to creator with the edit link" button for each event, in expanded view.

Someone who created their recurring event on the old calendar wanted to edit the event. I had to make them a password (I did this in the DB directly) and construct the edit link for them. This worked but it required me to ssh into the server and understand the table layout and know SQL.

I think there should be a button for "resend edit information" in the calendar that would send to the event creator an email:

1. if a password is already set, it would just contain a reminder of the existing edit link
2. otherwise, it would create and save a password, and send the edit link using it

This would let people self-serve on getting a "reminder" of their calendar password editing link (the single most frequent help request outside of bugs)

fix CMS to not remove the nav in the frontmatter for the theme

if you save an article with frontmatter like this:

 menu:	
    main:	
        parent: aboutmenu

then it is not preserved and the article drops out of the nav

calendar: Improve contrast of link color

I love the continuation of the classic site's orange theme on the new site. But there are a couple of places where orange is used for text on a white background, and it be a little difficult to read. It looks OK whe sitting on a laptop in a well-lit room, but it gets tougher when you are looking at the site on a mobile device in direct sunlight, etc. We expect people to use the site when out & about, so this is a likely scenario.

The usual standard for text color contrast is 4.5:1. When the current #FF8D00 orange is on a white background, the contrast is 2.3:1. (The exact meaning behind the ratio isn't particularly important, there are tools that do the math for you.)

There are numerous ways we could solve this and it comes down to which one we prefer aesthetically:

• Darken the current orange until it meets 4.5:1. Orange and yellow are notoriously difficult for color contrast, though. By the time you make them dark enough to meet the recommendation, they are more of a muddy brown than orange or yellow (e.g. #B36100).
• Use a different color already in use somewhere else on the site, such as the #0066BB blue used for some links on the calendar.
• Stick with the existing orange, but use it as a background highlight color behind the link text instead. (We would need to use a relatively dark text color for this to work.) This can look a little busy on pages with lots of links, but if we want orange above all then it is an option.
• Use another color entirely that we're not using anywhere right now, like green.

calendar: month-long "grid" view for events

this should look roughly like http://old.shift2bikes.org/cal/viewpp2018.php without the event listings below. It could (should?) certainly link to the individual link in the event listing for the event, but need not be in other ways an "event posting" tool, but more like an "event viewing" tool.

I understand this is a major lift, but it is also a frequent feature request.

calendar: feature request: special handling for removed rides

not sure what it could look like, but a suggestion was edit URL shows a "removed for CoC violation" ?

Let's not work on this til we think it's needed :)

Individual ride links don't work

1. Navigate to the events list: https://docs.shift2bikes.org/calendar/
2. Expand the details for any ride
3. Choose "Sharable link" (e.g. https://docs.shift2bikes.org/calendar/event-10541)

Result:
404 error

theme: do not show date listing from posts

Several beta testers' feedback mentioned that the dates showing on every page seemed useless or misleading. So I updated the CMS to not require the date and removed it from frontmatter on all pages except a couple where it seemed relevant.

Now all pages show "January 01 0001" as the date:

Could we get the theme updated so it doesn't automatically show the date? It's ok if it shows dates that are in the content (so: https://www.shift2bikes.org/playbooks/technology-playbook/ is ok if it stays) or if it doesn't, either way is fine.

Assigning @stephaniecp but she can turn me down if she wants :)

get legacy editing tools working in docker

@sdobz gave some notes that we're going to see if fool can decipher following the docs.

• find mapping for files into php
• update nginx configuration for php file location
• takes URL tells php where the URL is on the filesystem

Starting in docker-compose.yml and mounts from filesystem

calendar: Fix Open Graph tags for better social sharing of ride links

New ride links do work when shared to Facebook etc. but we can tidy up the Open Graph tags to pull in a better preview.

calendar: feature request - add ability to ban an email address from posting rides

to support our code of conduct.

calendar: Document Calendar API

We need to document the calendar API used by the back end. Most important is the read-only events endpoint, but documenting the full CRUD cycle would be useful. This should be in the form of API.md in the docs folder of this repo.

This is a necessary precursor to writing some kind of tests to run against it, so we can be confident that we're not going to break it when we make changes.

theme: create favicon

right now we have some letter u that is underlined.

calendar: reimpliment the pedalpalooza "month-long archive" view using the new codebase

on the old site, http://www.shift2bikes.org/cal/viewpp2017.php looked like the below screenshot. I couldn't capture a long enough shot but at the bottom should be a day-by-day ride listing. @sdobz suggested that we could "remake" it using the new codebase since it's basically 3 things:

1. static: poster image for $year + header info which talks about dates and number of rides
2. dynamic: month-long calendar view
3. dynamic & existing already: long calendar listing by day

These are mostly linked from and used from the archive page (docs.shift2bikes.org/archive/pedal-palooza-archives/) and is more important than simply a record of what happened - it's also an inspiration to future ride creators to browse what happened last year and in the more distant past.

Individual ride links don't work from Pedalpalooza events list

1. Navigate to the Pedalpalooza events list: https://docs.shift2bikes.org/pedalpalooza-calendar/
2. Expand the details for any ride
3. Choose "Sharable link" (e.g. https://docs.shift2bikes.org/pedalpalooza-calendar/event-11273)

Result:
404 error

This is similar to #44, and the fix is probably in the same vicinity as #67.

calendar: PP feature request - add total number of PP rides on the PP ride header

It'd be cool to show the number of PP events at the top of the PP page. You can see this in practice on the 2018 page (and other old pages): http://old.shift2bikes.org/cal/viewpp2018.php

fix CMS editing

at present whenever anyone tries to edit in the CMS they get an API_ERROR: failed to persist entry.

theme: thoroughly update website title

shouldn't say reboot

Footer should not say copyright

The footer says "Copyright (c) 2018, Shift2Bikes; all rights reserved." This information should be removed as there is no copyright, and the web development team is operating under the MIT license.

theme: document how menus on site are built and how theme is used

@carrythebanner and I had some trouble debugging a collision in page names that causes hugo to error out like this:

Error: Error building site: "/Users/jhetrick/Documents/z_etc/shift-docs/site/content/pages/pedalpalooza.md:1:1": duplicate menu entry with identifier "Pedalpalooza" in menu "main"

We were at a bit of a loss to figure out:

• what file was conflicting
• why it mattered (the same-named files were in different directories and shouldn't have conflicted).

What this issue requests is:

• an explanation of how the menu layout is created (we think it's largely based on frontmatter that exists in only SOME markdown files?). I'd suggest this belongs somewhere in the docs/ directory so people follow the intended pattern when creating new content. Maybe includes a "best practices for using/modifying this theme" too?
• some suggestions of how to debug problems like that. We never actually "solved it" - just worked around by renaming his page to something different.

Thanks for your help!

theme: When scrolling down, the viewport jumps to the bottom of the page when the top of the viewport hits the header

If you navigate to the main page and begin scrolling down, as soon as the top of the viewport hits the top of the header image, the viewport jumps to the bottom of the page.

content: create board of directors playbook aka "how shift is run"

should be in a similar style to the other playbooks (https://www.shift2bikes.org/pages/playbooks/). Should:

• be a markdown file in site/content/playbooks
• with similar frontmatter to the other playbooks so it ends up in the playbook nav
• and should mention our bylaws, meetings, and other similar stuff as well as the contact for the board

cc @designosaur

content: Accessible version of Ride Leading comic

The Ride Leading comic is super cool, but it's a plain old image. We should find a way to capture the the comic's words and the spirit of the illustrations as text.

Adding a mailing list page

All throughout the site, there are external links to riseup.net for the Shift email list. Notably, there's one in the top-level nav (under Community).

There should be a static content page for the mailing list which explains what it is, how to join, etc, with links out to riseup.net. Most or all of our content should then link to this mailing list page.

calendar: Create tests for API and front-end

It would be helpful to have a suite of tests that we can run to verify that important functionality still works. They should at least be available to run manually in your local dev environment; bonus points for automatically running on PRs, etc.

There are two main classes of tests needed:

• API
• website front-end

Conventional wisdom is to write tests in the same language as the application, so the dev environment and dev knowledge can be maximized. (So, PHP or Javascript in our case.) In practice, the best tests are the ones you actually run, so whatever we can reliably maintain is best. A lot of test frameworks use custom DSLs anyway, so aside from some syntax familiarity there may not be a ton of efficiency either way.

content: update umbrella playbook to include "receiving donations" & how to handle

calendar: prevent ULTRA-LONG date ranges for calendar event loads

We should protect against people loading >=32 days in one query to protect the server from people rage-clicking on a query that isn't working because it takes A While.

cc @carrythebanner who has a bit of an implementation already that just throws an error in the JS console which should be sufficient.

Fix logo alignment on mobile layout

When viewing the site on a mobile device/small screen, the Shift logo is right-aligned and can interfere with the hamburger menu. I might have caused this back when I switched the logo to SVG (#22).

Redirect /calendar/* to /calendar/index.html in netlify

The url https://docs.shift2bikes.org/calendar/event-1235 should direct to https://docs.shift2bikes.org/calendar/

calendar: should allow event submission w/o print info, if 'include in print calendar' is not selected

or we could just remove the "incude in print calendar" button and make those fields mandatory all the time. They help with a month-long-calendar-view even outside of PP

calendar: save event submission data before trying to process it

when people get a "server error" for saving their event, we can't tell what they did, and their description/partial repro data often doesn't show the problem again. So then we can't debug :|

It'd be awful cool if we could somehow save the data before trying to "do whatever might lead to a server error". I don't even know if that makes sense, but it would help us help them get it re-entered, and also letus debug whatever caused that...

theme: Update shortcut icons

On some platforms, there are additional icon files beyond the standard favicon for home screen shortcuts, bookmarks, etc. These icons may also be used for share links (see also #94).

For example, on my phone my bookmark for the Calendar page now shows an underlined "U" (which I guess is a default Hugo thing?).

content: link to hugo pages for pedalpalooza/etc

This is a feature request.

Now that we have the CMS working on all the content under /pages, it would be great if some of the other not-exactly-calendar content that is currently embedded in the calendar lived there too:

• http://www.shift2bikes.org/fun2/pedalpaloozaArchive
• header "info" block for http://www.shift2bikes.org/fun2/pedalpalooza (@carrythebanner will migrate his edits from betacal during migration to satisfy the edit request - that's non-trivial to move out of the cal)

hamburger/nav menu doesn't work on iphone

site nav does nothing (no links are ever shown/available on the iphone: the hamburger menu doesn't do anything if clicked.

Even without an iDevice, you can repro in safari using dev tools -> "responsive design mode":