Skip to content

Latest commit

 

History

History
167 lines (149 loc) · 8.96 KB

README.md

File metadata and controls

167 lines (149 loc) · 8.96 KB
Raw

Telescope - https://rcos.io

Telescope is the RCOS website.

Cargo Docker GitHub release version

User Notes

If you find issues with Telescope or have a feature you want added, please make an issue under the issues tab. You should also feel free to contribute your own. Pull requests are welcome. See below for detailed information on building & contributing to telescope.

Installation:

  1. Install dependencies:

    1. Rust (see https://www.rust-lang.org/ for more info) 
      curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
source ~/.cargo/env
    2. Hasura CLI to run database migrations. See the hasura CLI docs for more info. 
      curl -L https://github.com/hasura/graphql-engine/raw/stable/cli/get.sh | bash
    3. Docker and docker-compose to run telescope and the database locally. this can be a complicated process, but there are good instructions online here. Message me for help if you need it.

  2. Clone this repository:

    git clone --recurse-submodules https://github.com/rcos/Telescope.git

    You need to make sure you get all of the submodules here using --recurse-submodules otherwise you won't have any of the RCOS branding logos or icons, or any of the database migrations and setup.

  3. Copy the configuration templates as follows:

    • config_example.toml -> config.toml
    • .env.example -> .env (note: the config.toml and .env files must be created yourself.)

    Then modify them to match your environment. You may need to generate the GitHub related credentials. Go here to register a new GitHub OAuth application or get a new client secret. You will also have to create a discord OAuth app and bot token. Instructions can be found in config_example.toml.

    You must make sure that some of the items in the .env file match. For example, the database password in POSTGRES_PASSWORD needs to be the same as the one in DATABASE_URL. If you forget to do this, you will need to reset the database (docker-compose down --volumes).

  4. Build and start the docker images.

    docker-compose up -d

  5. Run the database migrations. Replace the "xx.." in the command with the admin secret from your .env file. Make sure the admin-secret is at least 32 characters long.

    hasura --project rcos-data/ migrate --admin-secret xxxxxxxxxxxxxxxxxxxxxxxx --endpoint http://localhost:8000 apply

  6. Track the Hasura tables: In Hasura (http://localhost:8000), enter your admin-secret when prompted. Navigate to the "Data" tab, and click "Create Table". Track all tables, and hit "Add Table". You also want to press "Track All" for the foreign key relationships as well.

  7. Reload metadata:

    hasura --project rcos-data/ metadata --admin-secret xxxxxxxxxxxxxxxxxxxxxxxx --endpoint http://localhost:8000 reload

  8. At this point Postgres, the Hasura GraphQL API, Caddy, and Telescope should all be running on your system in individual docker containers. Docker exposes the Hasura console at http://localhost:8000 and https://localhost:8001, and Telescope is exposed at https://localhost:8443. To shut them all down, run

    docker-compose down

    If you only want to make changes to telescope, you don't need to take down all the containers. Simply make your changes, run cargo check to verify that it compiles, and then rebuild just telescope in docker using

    docker-compose up --build -d

Running Telescope outside of Docker

Developing telescope with Docker is useful because you are testing Telescope in an almost identical environment to that which it runs on in production. In order to improve compile speed, due to the incremental compilation cache of Rust, you may want to develop and run Telescope outside of Docker. You can do this by following these optional instructions:

  1. Telescope typically uses the standard web port 80, but outside of Docker you will need to change that to 8080 by setting address to 0.0.0.0:8080 in config.toml. This is because port 80 is restricted.

  2. The commands you use to run and test Telescope need to be changed. To start the supporting services like Hasura, Postgres, and Caddy, run docker-compose -f docker-compose.dev.yml up -d. To start Telescope, run cargo run.

Development Notes

These are note for Telescope Developers on how to find and update Telescope itself.

Project Structure

Telescope is a large enough project that it may not be immediately obvious where certain files are. This section provides a map to this repository.

  • .github: This folder holds configuration files related to this repository's interactions with GitHub.com. This includes the GitHub issue templates, the continuous integration workflows, and the Dependabot configuration.
  • proposals: This folder contains the project proposal files that Telescope has been submitted under for the Rensselaer Center for Open Source (RCOS).
  • rcos-data: This git submodule points to the repository that contains the migrations for the central RCOS database.
  • graphql: This folder contains the introspected schema.json file for the central RCOS GraphQL API exposed via Hasura over the central RCOS database. This folder also contains GraphQL files for all of the different queries that Telescope will send to the central API.
  • static: This folder contains statically served files and assets, including
    • Telescope icons
    • RCOS icons and branding
    • The global CSS style file
    • All of Telescopes javascript
    • Sponsor logos and branding
  • templates: This folder contains all of the Handlebars templates used to render Telescope's frontend.
  • src: This is the main Telescope codebase, written in Rust.

Schema Introspection

When the central RCOS GraphQL API (a Hasura wrapper over the central RCOS Postgres database) gets updated, Telescopes schema needs to get updated to match. After merging whatever changes or migrations have been made to the telescope-dev-version branch of the rcos-data repository, update Telescope's git rcos-data submodule to point to the newest commit on the telescope-dev-version branch. After you have done this and pulled the submodule, update the local database using the hasura client. The commands should look like this:

hasura --project rcos-data/ migrate --admin-secret xxxxxxxxxxxxxxxxxxxxxxxx --endpoint http://localhost:8000 apply
hasura --project rcos-data/ metadata --admin-secret xxxxxxxxxxxxxxxxxxxxxxxx --endpoint http://localhost:8000 reload

where xxxxxxxxxxxxxxxxxxxxxxxx is replaced by the hasura admin secret in your .env file. After applying the migrations, go to the hasura console to make sure that all the proper tables are tracked, and all the types and queries are available. To go to the hasura console on your local machine, navigate to http://localhost:8000/console/settings/metadata-actions in your browser.

If you haven't already, you should install a GraphQL client to introspect the schema. There are several of these that are probably acceptable, but for consistency we use the graphql-rust client. Install this using the command from its README.

cargo install graphql_client_cli --force

Finally, regenerate Telescope's schema.json file as follows:

graphql-client introspect-schema --header 'x-hasura-admin-secret: xxxxxxxxxxxxxxxxxxxxxxxx' --output graphql/rcos/schema.json http://localhost:8000/v1/graphql

again, xxxxxxxxxxxxxxxxxxxxxxxx is replaced by the hasura admin secret in your .env file.

You may also have to introspect the GitHub V4 API schema, since we also keep a copy of that in telescope. This requires a GitHub Personal Access Token (PAT) which you can generate here. Once you have generated your PAT, you can introspect/update the local GitHub Schema using

graphql-client introspect-schema --output graphql/github/schema.json --authorization "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" https://api.github.com/graphql

where xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx is replaced by your PAT.