{"id":18620499,"url":"https://github.com/simonsobs/teleview","last_synced_at":"2026-02-16T22:09:09.498Z","repository":{"id":198527325,"uuid":"637886070","full_name":"simonsobs/TeleView","owner":"simonsobs","description":"A Web Portal for viewing Simons Observatory level-3 data","archived":false,"fork":false,"pushed_at":"2025-03-05T22:23:22.000Z","size":1163,"stargazers_count":0,"open_issues_count":4,"forks_count":0,"subscribers_count":3,"default_branch":"main","last_synced_at":"2025-03-31T08:06:47.862Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"bsd-2-clause","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/simonsobs.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2023-05-08T16:06:53.000Z","updated_at":"2025-03-05T22:23:24.000Z","dependencies_parsed_at":null,"dependency_job_id":"ec84d107-8391-4b39-9633-d958821ba3f8","html_url":"https://github.com/simonsobs/TeleView","commit_stats":{"total_commits":95,"total_committers":4,"mean_commits":23.75,"dds":"0.10526315789473684","last_synced_commit":"042a74081b470dd832eda88e9f33b249a3d43209"},"previous_names":["simonsobs/teleview"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/simonsobs%2FTeleView","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/simonsobs%2FTeleView/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/simonsobs%2FTeleView/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/simonsobs%2FTeleView/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/simonsobs","download_url":"https://codeload.github.com/simonsobs/TeleView/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":252839888,"owners_count":21812190,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-11-07T04:06:36.570Z","updated_at":"2026-02-16T22:09:09.461Z","avatar_url":"https://github.com/simonsobs.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# TeleView\nA Web Portal for viewing Simons Observatory data\n\nThe TeleView projects is a multi-language repository that is designed to operate four applications:\n\n1. A Django Website that provides an interface to database actions written in Python\n2. A MongoDB database that provides indexing and query capacities for a Host computers data file system(s).\n3. A Next.js-React (JavaScript) front-end that provides a graphical user interface for viewing data.\n4. An NGINX web server that provides a reverse proxy to the Django and Next.js-React applications as well as serving \nthe static data files on the host computer.\n\n\nEach application exists in a directory within the root TeleView folder.\nMost applications can be run independently in a standalone mode for debugging and testing;\nhowever, the applications are designed to run and be built together using Docker's compose.yaml files located in the\ncontent root.\n\n## Scope of this README.md\n\nThis README.md describes deployment of all applications together with Docker compose.\nFor information on testing or operating and individual applications, see the README.md file in that \napplication's directory.\n\n## TeleView Components Technologies Stack\n![TeleView components and relationships](static/TeleViewTechnologyStack.png \"TeleView Stack\")\n\n## Why name it TeleView?\n\n**TeleView** stands for **Tele**scope data **View**er.\nIn choosing this name I wanted a name that I\ncould easily type thousands of times, a name that was descriptive, and name that was memorable for people\nthat only use the application occasionally.\nThis is why the application sounds like \"television\";\nThis was amusing to me, and I made the favicon a black circle with yellow letters \"tv\" to give\nthe impression of a monochromatic cathode-ray tube.\n\n# Initial Setup\n\nTeleView is designed to work on any computer that is running Docker.\nIt will properly disturb my users, but this application was developed on a Windows 10 machine,\nusing Docker Desktop for Windows, and the Windows Subsystem for Linux (WSL2).\nTeleView gets test on a Mac and is deployed on a Linux server.\nIt should work on any computer that is running Docker.\n\n## Environment Variables\n\nTeleView uses environment variables to configure the applications.\nThese are found in a .env file in the root directly of this project.\n\n\u003e [!WARNING]\n\u003e The .env file is not included in the git repository and is ignored by git.\n\u003e This is because the .env file contains sensitive information.\n\n### Initial Setup\nCopy the .env-default file (in the root of the TeleView repository)\nto .env and edit the values to match your system.\n\nThe tvapp requires a special file named .env.production. See the \n/tvapp/.env.production.example to see what this file should look like.\nUse the convince script init.sh to automatically copy the relevant\nvariables from the root .env file to the tvapp/.env.production file.\n\nThe .env is a central location for a configuration distribution across\nthe TeleView applications. This file is expected and used by docker-compose,\nsee the compose.yaml file in the root of the TeleView repository.\nThe compose.yaml file distributes these variables to the applications,\nand each application has its own way of using these variables.\n\nSome variables are used by all applications, some are used by only one,\nsome are used only during the application build process, some are used\nonly the first time, and the application is run, while others can be changed\nwhen the application started at run-time. \nFind more on this in section \"All the rest of the environment variables\" below.\n\n### Pointing to data\nThe most important environment variable points to the data.\n```\n- TELEVIEW_PLATFORMS_DATA_DIR=/data_path/to_one_or_more_telescopes/\n```\nEdit this value in the .env file.\n\n\u003e [!NOTE]\n\u003e This can be an absolute or relative path on the Host computer.\n\nThis is a directory that should contain one or more folders meant to represent\nphysically separated systems (different telescopes).\n\nEach telescope folder should contain a folder named `smurf` that contains the data files.\nIn the future, it is our intention expanded to include other data types with diniated by\ndifferent folder names. For now, the only folder that is used is `smurf`. \nIf the data directory is missing or empty, the application will not identify that directory as a *platform*\nand any datafiles will not be indexed/available in the database.\n\n\u003e [!NOTE]\n\u003e **platform** is an important term in TeleView, and indicates an\n\u003e indexed data attribute used for filtering and returning data.\n\n![img.png](static/PlatformDirStructure.png)\nCaption: The directory structure. In the image example above, `TELEVIEW_PLATFORMS_DATA_DIR=/so/level2-daq/` While this directory has\nmultiple subdirectories, only the **lat** and **satp1** directories are indexed as a platforms. The other directories\nare either missing the expected data directory (only *smurf* is allowed at the time of writing) or their\nsmurf directory is empty, as is the case for **satp2** in this example.\n\n### Configuring the Website Host\n\nThe TeleView website is hard-coded to be served from a sub-directory \nof the host computer's web server. So if the host name is anywebsite.com,\nthen the TeleView website will be served from anywebsite.com/teleview/.\nIf you need to change this, I am sorry, but you will need to find and replace\nthe string \"teleview\" in the code, not an easy task for a repo named teleview.\n\nHowever, you can configure the hostname and port number by configuring the\n.env file.\n\nTo test on your local computer, I like to use the following values:\n```\nTELEVIEW_LOCALHOST_PORT=8111\nTELEVIEW_PUBLIC_SITE_HOST=http://localhost:8111\n```\n\nThe Port '8111' is less likely to be used by other applications, \nbut it means you will need to append this number to the host name.\n\nIf you only develop one website at a time on your local computer, you can \nuse port 80, which is the default port for http web traffic. This allows\nyou to omit the port number from the URL.\n\n```\nTELEVIEW_LOCALHOST_PORT=80\nTELEVIEW_PUBLIC_SITE_HOST=http://localhost\n```\n\nFor TeleView server deployment, you will need to add and extra layer of\nrouting to the NGINX configuration to route to port 443 (https) to port 80 (http).\nand to serve and verify SSL certificates. For the site computer, this\nis handled by a separate NGINX server that is not part of the TeleView.\nThat configuration looks like this:\n\n```\nTELEVIEW_LOCALHOST_PORT=8111\nTELEVIEW_PUBLIC_SITE_HOST=https://site.simonsobs.org/\n```\n\n### All the rest of the environment variables\n\nRun-time variables can be used to configure the applications\nwhen using `docker compose up` to initial the container network.\n\n\n```\nTELEVIEW_VERBOSE=0\nTELEVIEW_DEBUG=1\nTELEVIEW_MONGODB_PORT=27017 \nTELEVIEW_MONGODB_HOST=\"mongodb\"\nTELEVIEW_DEFAULT_ITEMS_PER_PAGE=200  # tvapp only\n```\n\nSome variables are needed at docker images build-time and are used\nin the Dockerfile for a given application. The following variables are used only\nin the tvapi (Django) application. You can see here that a root user is\ncreated for the admin access to the tvapi at container build-time, and these secrets\nare not exposed to the container at run-time.\n\n\n```\nDJANGO_SUPERUSER_USERNAME=\"root\"\nDJANGO_SUPERUSER_PASSWORD=\"I8pi4fun!\"\nDJANGO_SUPERUSER_EMAIL=\"chw3k5@gmail.com\"\n```\n\nThere are other variables that are used the first time an application is built.\nThis is true for the MongoDB image. The following variables are used\nto create a root user for the MongoDB database. It should be noted that these\nare run time variables that are needed by both tvapp and tvapi applications\nto log in to the MongoDB database.\n\n```\nTELEVIEW_MONGODB_ROOT_USERNAME=user\nTELEVIEW_MONGODB_ROOT_PASSWORD=pass\n```\n\n\n#### Setting up the docker environment \n\n## Docker, a few tips\nHelping install Docker is beyond the scope of this README.md. Here is the link, https://docs.docker.com/engine/install/,\nit is a little different in every operating system.\n\nIf you are going to work on this or any project that uses Docker, you may want to configure\nyour system to start docker when the system starts. \n\n\u003e [!WARNING] \n\u003e TeleView is set to start when Docker starts, it has the container `restart-policy` set to \"always\".\n\u003e This is the desired behavior for a production system, but it can be annoying when developing.\n\n\u003e [!NOTE]\n\u003e If you are developing this application, remember to clear the cache periodically so as not to\n\u003e overload your disk storage.\n\u003e `docker system prune --force --all` is a good command to know when\n\u003e starting your Docker journey.\n\n\u003e [!NOTE]\n\u003e It is the docker server that is required to be running. Most of the time that\n\u003e my docker commands fail it is because I forgot to start the docker server. \n\u003e To see if the docker-server is running,\n\u003e open a terminal and type `docker version`, you should see both **Client** and **Server** version information.\n\n\u003e [!Warning]\n\u003e For running scripts with docker commands. In Linux all docker commands need a `sudo` prefix,\n\u003e in macOS and Windows, using `sudo` is a mistake for docker. If you are running my TeleView scripts\n\u003e that contain docker commands, you will need to run the script with `sudo` if you are a Linux user.\n\u003e If you are on the site computer, you will not be able to run the scripts as general `sudo` usage is restricted.\n\n## The first build\n\nBefore calling the first `docker compose build` command it is necessary to create\na special file named .env.production. See the\n/tvapp/.env.production.example to see what this file should look like.\nUse the convince script init.sh to automatically copy the relevant\nvariables from the root .env file to the tvapp/.env.production file.\n\nYou will need to run the init.sh script everytime you change the .env file\nvariables that are used by the tvapp application. This is good reason to\neliminate the need for the .env.production file, but that was not done at\nthe time of writing.\n\n## The first run\n\nThe first time the TeleView system is run from a `docker compose up` command,\nThe MongoDB database will be initialized with a root user and password.\nThe database initialization creates a number of files in the `./mongo` directory.\nThis directory is empty when the TeleView repository is cloned from GitHub,\nand only includes a single .gitingore that instructs git to ignore all files in the mongo directory.\n\n## Subsequent builds\nYou can always use the top level convince script `build.sh` to \n\n1. build all the images\n2. stop all running containers,\n3. remove the shared volumes\n4. call the init.sh script to refresh the .env.production file from the current\n.env file\n5. deploy a test application on the localhost\n6. tag the images with the current git commit hash and project version number, \n7. push the images to the GitHub container repo.\n\nI use the script and then call control-C to stop when issue to exit the\nscript if I see issues.\n\nOf course, you may find yourself on a Lennox machine where you do not have sudo access\nneeded to run docker commands in a script. Maybe you are good at remembering  \naccurately typing a number of docker commands, and you want to look cool\nlike the hackers shown in movies. See the following section for a list of\ndocker commands that you can run manually.\n\n## Docker commands\n\nOn Windows, there is no sudo. \nOn Linux, you will need to use sudo for all docker commands.\nOn Mac, Docker gets mad at you if you use sudo. \n\n### Is docker on?\n\nSee is the Docker **serve** (daemon) is running (not *just* the client)\n\n```\ndocker version\n```\n\n### To stop the running containers and remove the shared volumes\n\nIt is important to add the `-v` option to remove the shared volumes,\notherwise the files in these volumes will persist and be used the next time\ninstead of new files being created at docker image build time.\n\n```\ndocker compose down -v\n```\n\n### To build the images\n\nIt should be noted that the build command can be run before calling the down command.\nI do the have the least amount of downtime for the TeleView website.\nI like the order of build, down, then up.\n\n\n```\ndocker compose build\n```\n\nDuring development on my local machine, when downtime is not an issue,\nI will often use the following command to build the images and start the containers.\nat the same time. This is not recommended for production.\n\n```\ndocker compose up --build\n```\n\n### To start the containers\n\nIn production, the final command I call to start the containers also adds the\n`-d` option to run the containers in the background. This way I can close the\nterminal and the containers will continue to run.\n\n```\ndocker compose up -d\n```\n\nIn development, I do not use the `-d` option so that I can see the output\nfrom the containers in the terminal and use control-C to stop the containers.\n\n```\ndocker compose up\n```\n\n### Login to the GitHub container registry\n\nThe TeleView images can be built then pushed to (pulled from) the GitHub container repository.\nTo log in to the GitHub container registry, use the following command:\n\n```\ndocker login ghcr.io\n```\n\n### Tag the images\n\nI could not find a good way to tag the images using the compose.yaml file.\nIt only allowed for one tag, and I wanted to use that to indicate the\n`LATEST` tag.\n\nSo I wrote a small script to tag the images with the `docker tag` command.\nCall this script from the root of the TeleView repository.\nThis tags the images with the current version number and the current\ngit commit hash.\n\n```\n./scripts/tag-images.sh\n```\n\n### Push the images to the GitHub container registry\n\nThe TeleView images can be built then pushed to (pulled from) the GitHub container repository.\nTo push the images to the GitHub container registry, use the following command:\n\n```\ndocker compose push\n```\n\n### To pull the images from the GitHub container registry\n\n```\ndocker compose pull\n```","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsimonsobs%2Fteleview","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsimonsobs%2Fteleview","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsimonsobs%2Fteleview/lists"}