PubPub Platform

Open-source technology for creating full-stack knowledge applications for communities of all types.

As noted in our recent announcement, Knowledge Futures has been hard at work on PubPub Platform, a tool that allows communities of all kinds to build knowledge applications tailored to their needs. We believe PubPub platform offers a major improvement for communities that want more flexibility, customization, and the ability to either use centralized hosting or self-host, while keeping the experimental, easy-to-use philosophy that Knowledge Futures has always strived for. We invite you to install and explore the alpha version of PubPub Platform, and we welcome your feedback.

Learn More: Documentation | PubPub Platform | Knowledge Futures | Newsletter | Roadmap

PubPub Platform is currently an alpha release, which means the code is subject to frequent, breaking changes. We do not yet recommend running PubPub Platform for production projects.

Community Guidelines and Code of Conduct

Knowledge Futures intends to foster an open and welcoming environment that aligns with our core values of ACCESS (accessibility, collaboration, curiosity, equity, and systemic outlike). As such, we require that all employees and members of our open-source community adhere to our Code of Conduct in all interactions in this and other Knowledge Futures repositories, including issues, discussions, comments, pull requests, commit messages, code, and all other messages.

Repository Structure

This repo is built as a monorepo that holds first-party components of PubPub. There are four primary sections:

root
├── core/
├── infrastructure/ 
├── integrations/ (deprecated)
├── jobs/
├── packages/
└── ...

• core holds the primary web application.
• infrastructure holds the deployment infrastructure for the centrally hosted version of PubPub Platform run by the Knowledge Futures team.
• integrations (deprecated) holds the integrations developed by the PubPub team. This will be removed in the near future.
• jobs holds the job queueing and scheduling service used by core.
• packages holds libraries and npm packages that are shared by core, jobs, and infrastructure.

To avoid inconsistencies and difficult-to-track errors, we specify a particular version of node in /.nvmrc (currently v20.17.0). We recommend using nvm to ensure you're using the same version.

Local Installation

This package runs the version of node specified in .nvmrc (currently v20.17.0) and uses pnpm for package management. All following commands are run from the root of this package.

To get started, clone the repository and install the version of node specified in .nvmrc (we recommend using nvm.

Next, install pnpm (likely using npm via npm install -g pnpm).

Then, from the root of the repository, run:

pnpm install
pnpm build

Running build when getting started with this repo is important to make sure the any prebuild scripts run (e.g. Prisma generate).

Depending on which app or package you are doing work on, you may need to create a .env.local file. See each package's individual README.md file for further details.

Development

To run all packages in the monorepo workspace, simply run:

pnpm dev:setup
pnpm dev

Often, you'll only want to run a specific package's dev script. In that case, use pnpm filters:

pnpm dev --filter core    // Runs just the `core` packages dev script
pnpm dev --filter core... // Runs just the `core` package and its dependencies dev scripts

Note that the term following --filter is the name of the package as specified in package.json, not the folder name (even though those may sometimes be identical).

You can also use filters to run package-specific commands, by placing the --filter flag before the script name:

pnpm --filter core reset
pnpm --filter core migrate-dev

Self-Hosting and Deployment

Guidance for self-hosting and deployment is coming soon. In the meantime, you can read about how we currently deploy the app in DEVELOPMENT.md. With small modifications, most development teams can use the included terraform configuration to run the app on commodity cloud infrastructure of their choice.

Bugs, Feature Requests, Help, and Feedback

We use the Discussion Forum for feature requests, ideas, and general feedback, and GitHub Issues for day-to-day development. Thus, if you're unsure where to post your feedback, start with a discussion. We can always transfer it to an issue later if needed.

Bugs

If you have a specific bug to report, feel free to add a new bug issue to the PubPub Platform Repo. If you submit a bug, we ask that you use the available template and fill it out to the best of your ability, including information about your browser and operating system, detailed, written step-by-step instructions to reproduce the bug and screenshots or a screen recording when relevant. Having all of this information up-front helps us solve any issues faster.

Please search the issue list first to make sure your bug hasn't already been reported. If it has, add your feedback to the preexisting issue as a comment.

Feature Requests, Feedback, and Help

If you have a feature request, idea, general feedback, or need help with PubPub, we'd love you to post a discussion on the Discussion Forum. As with bug reports, make sure to search the forum first to see if the community has already discussed your idea or solved your issue. If we have, feel free to join in on that ongoing discussion. Remember to be polite and courteous. All activity on this repository is governed by the Knowledge Futures Code of Conduct.

Contributing

In the coming weeks, we'll be developing more thorough contribution guides, particularly for contributors interested in:

• Extending PubPub Platform with new Actions and Rules
• Extending the PubPub Platform API
• Contributing to self-hosting scripts and guides on common cloud hosting
• Contributing documentation for developers or users

For now, you can browse the issue list and comment on any issues you may want to take on. We'll be in touch shortly

Pull Requests

Our preferred practice is for contributors to create a branch using the format initials/descriptive-name and submit it against main.

Request names should be prefixed with one of the following categories:

• fix: for commits focused on specific bug fixes
• feature: for commits that introduce a new feature
• update: for commits that improve an existing feature
• dev: for commits that focus solely on documentation, refactoring code, or developer experience updates

Request descriptions should use to our Pull Request template, including a clear rationale for the PR, listing any issues resolved, and describing the test plan for the request, including both tests you wrote and step-by-step descriptions of any manual QA that may be needed.

Finally, we request that any complex code, new terminology, potentially decisions you made, or any areas you'd like feedback on be commented on inline in GitHub's files changed interface.

User-Facing Documentation

User-facing documentation is a work in progress, and can be found at https://knowledgefutures.helpjuice.org.

Supporting Services

Thank you to these groups for providing their tools for free to PubPub's open source mission.