Static sites with superpowers
Staticman is a Node.js application that receives user-generated content and uploads it as data files to a GitHub and/or GitLab repository. In practice, this allows you to have dynamic content (e.g. blog post comments) as part of a fully static website, as long as your site automatically deploys on every push to GitHub and/or GitLab, as seen on GitHub Pages, GitLab Pages, Netlify and others.
It consists of a small web service that handles the POST requests from your forms, runs various forms of validation and manipulation defined by you and finally pushes them to your repository as data files. You can choose to enable moderation, which means files will be pushed to a separate branch and a pull request will be created for your approval, or disable it completely, meaning that files will be pushed to the main branch automatically.
You can download and run the Staticman API on your own infrastructure, build to Docker image, deploy on Heroku or Google Cloud Functions.
This is a fork of eduardoboucas/staticman aiming to meet the requirement to deploy on Google Cloud Functions. Runtimes likes Heroku or Docker may still be supported, but they won't get much caring.
- Node.js 10+
- npm
- A personal access token for the GitHub and/or GitLab account you want to run Staticman with, or a GitHub App ID and private key to run as GitHub App.
- An RSA key in PEM format
-
Clone the repository and install the dependencies via npm.
git clone [email protected]:pingu8007/staticman.git cd staticman npm install
-
Create a development config file from the sample file.
cp config.sample.json config.development.json
-
Edit the newly-created config file with your GitHub and/or GitLab credential, RSA private key and the port to run the server. Click here for the list of available configuration parameters.
-
Start the server.
npm start
Each environment, determined by the NODE_ENV environment variable, requires its own configuration file. When you're ready to push your Staticman API live, create a config.production.json file before deploying.
Check this guide if you're using Docker.
To deploy on heroku, click the following button than fill in the App name and region you want.
In order to configure credentials for GitHub and/or GitLab as well as RSA private key, go to Config Vars section under App's setting page and fill-in those variables. Reference to config.js for variable name.
-
Create project and enable billing on Google Cloud. You should get your trial credits if you are first time.
-
Enable Cloud Functions API for your project.
-
Follow the Bare metal section to clone project and create production config file (
config.production.json). You don't need to install (npm install) or start (npm start) it, Google will install for you. -
Deploy to your Google Cloud project.
gcloud functions deploy <FUNCTION_NAME> \ --allow-unauthenticated \ --runtime=nodejs10 \ --trigger-http \ --source=./
You need to auth yourself if you are first time to the
gcloudcommand. You may need to specify your project, region, memory or other arguments for better cost/performance balance. Check the document for details.
Staticman runs as a bot using a GitHub and/or GitLab account, as opposed to accessing your account using the traditional OAuth flow. This means that you can give it access to just the repositories you're planning on using it on, instead of exposing all your repositories.
To add Staticman to a repository, you need to add the bot as a collaborator with write access to the repository and ask the bot to accept the invite by firing a GET request to this URL:
http://your-staticman-url/v2/connect/GITHUB-USERNAME/GITHUB-REPOSITORY
Staticman will look for a config file. For the deprecated v1 endpoints, this is a _config.yml with a staticman property inside; for v2 endpoints, Staticman looks for a staticman.yml file at the root of the repository.
For a list of available configuration parameters, please refer to the documentation page.
Would you like to contribute to Staticman? That's great! Here's how:
- Read the contributing guidelines
- Pull the repository and start hacking
- Make sure tests are passing by running
npm test - Send a pull request and celebrate