EdgeDB.com (mirror)

Note

This repo is a read-only mirror of the production branch of a private repo that contains the source code for edgedb.com.

This repository contains the code and the content necessary to generate the EdgeDB web site, including the blog, documentation, tutorial and Easy EdgeDB book.

We use Sphinx and Next.js to generate the Web content from .rst sources.

Requirements

• Python 3.8+
• Node.js 12+
• Go 1.15+
• Yarn
• Dart 2.17+

Note: If developing on Windows, it is recommended to use WSL since the various setup/build scripts assume a unix-like environment.

Installation

1. Clone the repository:

$ git clone --recursive [email protected]:edgedb/edgedb.com.git

2. Install JS dependencies:

$ yarn install

3. Reuse EdgeDB repos already on the system (optional step)

Symlink EdgeDB repos into ./.repos. Check setup.sh in the root of this project to see which repos need to be present. You may skip this step to allow setup to automatically clone all the repos for you.

4. Set up Sphinx

$ yarn setup

Run yarn setup to automatically install sphinx and python deps, clone the required repos to fetch the docs from, and create the config files needed for sphinx docs building. Re-run yarn setup at any time to pull the latest changes for each repo.

5. Set up the tutorial database (optional step)

By default, the website app is pre-configured to use the production DB for running the local tutorial app. It is possible, though, to configure it to use a local DB instance.

First create a new EdgeDB instance. You can name it anything; for simplicity, we use the name tutorial below.

$ edgedb instance create tutorial

When running the tutorial instance you'll need to set the EDGEDB_DEBUG_HTTP_INJECT_CORS environment variable to true (1) and run the server in --foreground mode:

$ edgedb instance stop tutorial
$ env EDGEDB_DEBUG_HTTP_INJECT_CORS=1 edgedb instance start
    --foreground tutorial

Copy the contents of .env.sample into a new file called .env and update NEXT_PUBLIC_EDGEDB_SERVER and NEXT_PUBLIC_EDGEDB_TUTORIAL_DB values. You can find the instance port by running edgedb instance status. The default database name is edgedb.

Finally, migrate the new 'tutorial' instance to the schema in content/tutorial/dbschema:

$ edgedb -I tutorial migrate --schema-dir content/tutorial/dbschema

6. Run yarn regenGrammar if there have been changes to the EdgeQL grammar. Skip this step otherwise.
7. Run yarn dev. This will run all the build steps needed for the docs, blog, tutorial and Easy EdgeDB, then start the next.js dev server. It will also watch for changes in the source files and re-run build steps as needed.

$ yarn dev

# Can skip/only run certain build steps with the --skip or --only flags
# with a comma separated list of any of: 'docs', 'blog', 'easyedb',
# 'tutorial', 'nextjs'
# For example, if you're only working on the docs and blog content, and
# don't have the tutorial instance running, you can run the following to
# skip building other parts of the site:
$ yarn dev --skip easyedb,tutorial
# ...or, for example, you're just writing a blog post:
$ yarn dev --only blog,nextjs

8. To run a full build.

$ yarn build

# to serve static build
$ yarn next start

Configuration

Before running yarn dev/yarn build, customize the paths in which documentation sources are looked for by creating the build.config.ts file in the root directory with the following content:

import {BuildConfig} from "./dataBuild/interfaces";

const config: BuildConfig = {
    repoPaths: {
        edgedb: "<path-to-the-core-repo>",
        js: "<path-to-the-js-docs-repo>",
        python: "<path-to-the-python-docs-repo>",
        go: "<path-to-the-go-repo>",
        dart: "<path-to-the-dart-repo>",
        easyedb: "<path-to-the-easyedb-repo>",
    },
    // required when not manually running build inside virtual env
    sphinxPath: "<path-to-sphinx-build>"
}

export default config;

Fetch Tweets

The tweets on the community page are loaded from the file ./dataSources/twitter/tweetData.js. This file is committed to the repo and generated with the command yarn fetchTweets. Before running this command create a file at /buildScripts/fetchTweets/twitterAuth.config.ts with a default exported object containing a twitter api key/secret and access token/secret (implementing the TwitterAuthConfig interface from oauth.ts). Eg.:

import type {TwitterAuthConfig} from "./oauth";

const config: TwitterAuthConfig = {
  apiKey: "...",
  apiKeySecret: "...",
  accessToken: "...",
  accessTokenSecret: "...",
};

export default config;

Remote EdgeDB Instance

The tutorial runs on a remote instance that exists independently of this repo. The instance is stateless as we discard all the changes we do in the examples, however it still requires the schema and data to be set up for us to use. This is done via appropriate migration scripts found here:

https://github.com/edgedb/cloud/tree/master/docker/embedded/dbschema

Typically, if you're changing the tutorial database, you would first make a local copy for testing the changes and then you can backup the dbschema both in this repo (as a reference) as well as in the repo above (to make the changes live).