Telescope is the RCOS website.
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.
Install dependencies:
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
source ~/.cargo/env
curl -L https://github.com/hasura/graphql-engine/raw/stable/cli/get.sh | bash
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.
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
).
Build and start the docker images.
docker-compose up -d
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
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.
Reload metadata:
hasura --project rcos-data/ metadata --admin-secret xxxxxxxxxxxxxxxxxxxxxxxx --endpoint http://localhost:8000 reload
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
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:
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.
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
.
These are note for Telescope Developers on how to find and update Telescope itself.
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
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.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.