docs: improve quickstart guide with Java version, transit data links,…#168
docs: improve quickstart guide with Java version, transit data links,…#168Hitanshi7556 wants to merge 2 commits intoOneBusAway:mainfrom
Conversation
… and additional resources
|
@tarunsinghofficial |
There was a problem hiding this comment.
Pull request overview
Updates the Quickstart Guide to better orient new users toward the recommended deployment path while improving prerequisites and data acquisition guidance for the legacy WAR-based quickstart flow.
Changes:
- Replaced the outdated-banner messaging with a clearer note pointing new users to the Render.com deployment guide.
- Clarified Java requirements (Java 11+, recommending Java 17 LTS) and added memory guidance for large feeds.
- Expanded transit data guidance with direct links to feed catalogs and a suggested test feed, and added a “Need Help?” resources section.
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| Download one of the quickstart `.war` files from our | ||
| [Downloads page](/downloads): | ||
|
|
||
| * The full webapp: `onebusaway-quickstart-assembly-webapp.war` - Includes the [REST API](/api/where) and [the web interfaces](/features/web). | ||
| * The API-only webapp: `onebusaway-quickstart-assembly-api-webapp.war` - Includes just the [REST API](/api/where). |
There was a problem hiding this comment.
The quickstart WAR filenames listed here don’t match the actual filenames shown on the Downloads page (they include the OBA version, e.g., onebusaway-quickstart-assembly-<version>-webapp.war). This also makes the later java -jar onebusaway-quickstart-assembly.war examples ambiguous. Consider updating this section to use the real download filenames (or a clear <version> placeholder) and ensure the command examples reference the same WAR name(s).
|
|
||
| ## Need Help? | ||
|
|
||
| If you run into issues, check out our [Troubleshooting Guide](/guides/troubleshooting-guide). For more information on deployment, see the [Render.com Deployment Guide](/guides/deployment/render). You can also reach out on our [community Slack](https://onebusaway.slack.com), report issues on [GitHub](https://github.com/OneBusAway/onebusaway-docs/issues), or check out the [onebusaway-docker repository](https://github.com/OneBusAway/onebusaway-docker). No newline at end of file |
There was a problem hiding this comment.
The Slack link points directly to the workspace (https://onebusaway.slack.com), which typically won’t be accessible to new users without an invite. Elsewhere the docs direct users to request an invitation via email (see src/getting-help.md). Consider linking to the Getting Help page (or including the invite instructions here) so new users have a working path to join Slack.
| If you run into issues, check out our [Troubleshooting Guide](/guides/troubleshooting-guide). For more information on deployment, see the [Render.com Deployment Guide](/guides/deployment/render). You can also reach out on our [community Slack](https://onebusaway.slack.com), report issues on [GitHub](https://github.com/OneBusAway/onebusaway-docs/issues), or check out the [onebusaway-docker repository](https://github.com/OneBusAway/onebusaway-docker). | |
| If you run into issues, check out our [Troubleshooting Guide](/guides/troubleshooting-guide). For more information on deployment, see the [Render.com Deployment Guide](/guides/deployment/render). For community support and Slack join instructions, see [Getting Help](/getting-help). You can also report issues on [GitHub](https://github.com/OneBusAway/onebusaway-docs/issues), or check out the [onebusaway-docker repository](https://github.com/OneBusAway/onebusaway-docker). |
There was a problem hiding this comment.
Pull request overview
Copilot reviewed 1 out of 1 changed files in this pull request and generated 4 comments.
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
|
|
||
| ## Need Help? | ||
|
|
||
| If you run into issues, check out our [Troubleshooting Guide](/guides/troubleshooting-guide). For more information on deployment, see the [Render.com Deployment Guide](/guides/deployment/render). You can also reach out on our [community Slack](https://onebusaway.slack.com), report issues on [GitHub](https://github.com/OneBusAway/onebusaway-docs/issues), or check out the [onebusaway-docker repository](https://github.com/OneBusAway/onebusaway-docker). No newline at end of file |
There was a problem hiding this comment.
The “community Slack” link goes directly to the workspace URL (https://onebusaway.slack.com), which typically isn’t usable for new users without an invite. Consider linking to the existing “Getting Help” page (which documents how to request an invitation) or to the invitation email address instead, to avoid a dead-end for newcomers.
| If you run into issues, check out our [Troubleshooting Guide](/guides/troubleshooting-guide). For more information on deployment, see the [Render.com Deployment Guide](/guides/deployment/render). You can also reach out on our [community Slack](https://onebusaway.slack.com), report issues on [GitHub](https://github.com/OneBusAway/onebusaway-docs/issues), or check out the [onebusaway-docker repository](https://github.com/OneBusAway/onebusaway-docker). | |
| If you run into issues, check out our [Troubleshooting Guide](/guides/troubleshooting-guide). For more information on deployment, see the [Render.com Deployment Guide](/guides/deployment/render). You can also visit our [Getting Help](/getting-help) page to request a community Slack invitation, report issues on [GitHub](https://github.com/OneBusAway/onebusaway-docs/issues), or check out the [onebusaway-docker repository](https://github.com/OneBusAway/onebusaway-docker). |
| At a bare minimum, you'll need [Java](http://www.java.com/en/) installed on your system. You will also need the | ||
| following: | ||
| You will need Java installed on your system. Specifically, you'll need **Java 11 or later** (Java 17 LTS is recommended). | ||
| You can download a free JDK from [Adoptium](https://adoptium.net/temurin/releases/?version=17). After installing, verify the installation by running `java -version` — you should see something like `openjdk version "17.x.x"`. |
There was a problem hiding this comment.
This section says “Java 11 or later” but the Adoptium download link is hard-coded to Java 17. To reduce confusion for users who might want Java 11, consider either linking to both 11 and 17, or adjusting the wording to explicitly recommend Java 17 only (if that’s the true requirement for the quickstart WAR).
| You can download a free JDK from [Adoptium](https://adoptium.net/temurin/releases/?version=17). After installing, verify the installation by running `java -version` — you should see something like `openjdk version "17.x.x"`. | |
| You can download a free JDK from Adoptium for [Java 11](https://adoptium.net/temurin/releases/?version=11) or [Java 17](https://adoptium.net/temurin/releases/?version=17). We recommend Java 17 for new installations. After installing, verify the installation by running `java -version`. |
| ## Download a Quickstart Bundle | ||
|
|
||
| You need to download one of the quickstart bundles. Pick a bundle based on what features you are interested in: | ||
| Download one of the quickstart `.war` files from our | ||
| [Downloads page](/downloads): | ||
|
|
||
| * The full webapp: `onebusaway-quickstart-assembly-webapp.war` - Includes the [REST API](/api/where) and [the web interfaces](/features/web). | ||
| * The API-only webapp: `onebusaway-quickstart-assembly-api-webapp.war` - Includes just the [REST API](/api/where). | ||
|
|
There was a problem hiding this comment.
The guide lists unversioned quickstart WAR filenames, but the Downloads page typically serves versioned artifacts and later examples also show versioned names. Consider updating the bullet list (and/or the placeholder filename used in commands) to match the actual naming pattern users will download, so they don’t look for a file that doesn’t exist.
| **NOTE**: For new users, we recommend starting with our [Render.com Deployment Guide](/guides/deployment/render), which uses our official Docker image and is actively maintained. The guide below covers the legacy WAR-based approach and can still be useful for evaluation or custom deployments. | ||
|
|
||
| Also, to simplify testing your new server on our mobile apps we are adding support for custom URL schemes on our iOS and Android apps that will add your custom region to the app. Make sure the tasks are complete and that you're using an up-to-date app version to ensure this feature works. | ||
|
|
||
| * [Android task](https://github.com/OneBusAway/onebusaway-android/issues/1179) | ||
| * [iOS task](https://github.com/OneBusAway/onebusaway-ios/issues/719) | ||
|
|
||
| Example URL for a Davis, CA (Unitrans) server: | ||
|
|
||
| <a href="onebusaway://add-region?name=Unitrans&oba-url=https%3A%2F%2Fonebusaway-api-server-7mb1.onrender.com%2Fonebusaway-api-webapp">onebusaway://add-region?name=Unitrans&oba-url=https%3A%2F%2Fonebusaway-api-server-7mb1.onrender.com%2Fonebusaway-api-webapp</a> | ||
|
|
||
| ------------ | ||
| --- |
There was a problem hiding this comment.
The PR description lists the documentation improvements, but it doesn’t mention that the mobile-app custom URL scheme section (and linked Android/iOS tasks) was removed from this page. If that removal is intentional, please reflect it in the PR description (or briefly note why it’s no longer applicable) so reviewers understand the scope change.
Fixes #95
Changes