Skip to content

Latest commit

 

History

History
87 lines (64 loc) · 5.04 KB

README.md

File metadata and controls

87 lines (64 loc) · 5.04 KB
Raw

Slate development

This document describes

  • how to build and run Slate locally, and
  • how to make it publicly accessible by deploying to Netlify or Heroku.

Building Slate

  1. Install the following software:
  2. Make sure the programs git, code, and npm can be started from the command line, i.e. are accessible via the PATH environment variable.
  3. In a terminal, in a directory of your choice, run 
    git clone --recursive https://github.com/SReichelt/slate.git
cd slate
npm install
npm run build

Rerun npm install and npm run build after a pulling a new version from the repository.

Running Slate locally

  1. First, follow the steps for 'Building Slate' above, except for npm run build.
  2. Start Visual Studio Code, and open the workspace Slate.code-workspace.
  3. Now you should be able to execute the app via the run configuration "Launch with Chrome" or "Launch with Firefox".
  4. If the app does not start, check all output/console/terminal windows of Visual Studio Code for errors.
  5. Optional: To debug GitHub support, set up an OAuth application at https://github.com/settings/developers.
    • Enter http://localhost:3000/ for the callback URL.
    • After creating the application, add environment variables GITHUB_CLIENT_ID and GITHUB_CLIENT_SECRET to your local machine, according to the values reported by GitHub.

Running the VSCode extension

  1. First, follow the steps for 'Building Slate' above. (Note that in contrast to the first item under "Running Slate locally", the embedded webview of the VSCode extension will actually use the output of npm run build.)
  2. Open the separate workspace Slate-vscode.code-workspace.
  3. Click "Run / Start debugging" (F5).

Installing the locally built VSCode extension

When developing Slate, you will probably want to install the locally built version of the VSCode extension instead of the published version.

  1. First build Slate as described above.
  2. Open a terminal in the VSCode extensions folder.
  3. Create a symbolic link to the src/vscode subdirectory of Slate:
    • On Linux, use 
      ln -s <path>/src/vscode slate
    • On Windows, use mklink with the /d option, or New-Item in PowerShell.

Deploying to Netlify or Heroku

Creating a new public installation of Slate is very simple, and should work out of the box on Netlify. There is a provider-specific part and some provider-independent configuration.

Netlify

Netlify is recommended because its serverless architecture reduces costs and is potentially faster. However, this means that the site runs differently from what you can reproduce locally.

  1. Log in with your GitHub account at https://www.netlify.com/.
  2. Follow the steps to create a new site based on the GitHub repository. Leave all settings empty because they are already configured in netlify.toml.

Heroku

  1. Create an account at https://www.heroku.com/.
  2. Create a new Node.js app.
  3. Either configure the app to track your GitHub repository, or add Heroku as a Git remote and push to it (see https://devcenter.heroku.com/articles/git).

Common configuration

The steps above should be sufficient to create a read-only installation of Slate. Verify that the Netlify/Heroku build was successful and that the website can be accessed.

  1. To allow users to submit modifications, some environment variables (called "Config Vars" in Heroku) need to be set up in the app settings. For anonymous contributions, add the following variables:
    • MAIL_HOST: Hostname of an SMTP provider of your choice.
    • MAIL_USER, MAIL_PASSWORD: Login for the SMTP provider.
    • MAIL_FROM, MAIL_TO: Email headers for submission mails.
  2. To let users submit GitHub pull requests, you need to set up your OAuth application at https://github.com/settings/developers. For the callback URL, enter the public URL of the app. Then add the following environment variables:
    • GITHUB_CLIENT_ID: The client ID generated by GitHub.
    • GITHUB_CLIENT_SECRET: The GitHub secret generated by GitHub.
    • GITHUB_REDIRECT_URL (optional but recommended): The exact redirect URL as expected by GitHub. In particular, you may run into problems with HTTP vs. HTTPS if you don't specify this.

On Netlify, you need to manually trigger a new deployment after changing variables.

Unless configured differently, the new installation behaves like the official installation in that it will load library data from https://github.com/SReichelt/slate-hlm.git and also submit pull requests to that repository. Currently, the easiest way to set up a custom library would be to edit data/libraries/libraries.json.