civis-services-streamlit

This repository provides the following components:

• A Docker image to support Streamlit applications on Civis Platform
• A demo Streamlit app that's readily deployable on Civis Platform

Quickstart Using the Demo Application

To get a sense of what a Streamlit app looks like on Civis Platform:

• Log on to Civis Platform.
• From the top navigation bar, click "Publish".
• Under "Services", click "Streamlit Demo".

These steps create a new Civis Platform service configured for a Streamlit demo app pointing to this GitHub repository. The app is now ready to be deployed. Please follow these instructions for service deployment.

If you would like to start making the demo app your own by making code changes, you may fork this GitHub repository (note: your fork would be public; GitHub only allows public forks from a public repository) where the demo app's source code is in the directory demo_app/. If you would like to host and use your own Docker image, Dockerfile and entrypoint.sh from this GitHub repository define the civisanalytics/civis-services-streamlit image that you may like to modify and then host on your own DockerHub account.

Building and Deploying Your Streamlit Application

If you would like to build your own Streamlit application from scratch and deploy it on Civis Platform, here are the requirements.

1. Your Streamlit application must have its source code hosted on a GitHub repository. The Civis Platform user account that's going to deploy this Streamlit app must have access to this GitHub repo.

2. The following explains the expected files for your app:

   • app.py

     A required file. app.py is your Streamlit app's entry point. For which Python version you should use (e.g., Python 3.12), it is determined by which Docker image name and tag you're going to use to deploy your app on Civis Platform. The Python version is specified by the base image in the file Dockerfile of this GitHub repo.

   • requirements.txt

     A strongly recommended file, though not strictly required. requirements.txt specifies the Python dependencies to be installed for your Streamlit app to work. Note that streamlit itself should be one of the packages specified (so that you can pin the specific Streamlit version for your use case). If requirements.txt is present, the command pip install -r requirements.txt will be run to install these dependencies.

   • pyproject.toml

     An optional file. If a Python package needs to be installed in order for your Streamlit app to work, pyproject.toml plus the associated package code must be present. If pyproject.toml is detected, pip install --no-deps -e . will be run to install your Python package (--no-deps for not installing dependencies defined in pyproject.toml, because they should already be specified in requirements.txt above).

   • .streamlit/config.toml

     An optional file. These are Streamlit options, if you need to configure them. Reference: https://docs.streamlit.io/develop/api-reference/configuration/config.toml

3. Once your app code is on a GitHub repo, either create a new service on Civis Platform by following this page, or launch a Streamlit template service from Civis Platform's top navigation bar -> Publish -> Services -> Streamlit Demo. Specify or adjust the GitHub repo URL as well as the Git tag (or branch, or Git commit hash).

4. If your code is at a directory in your repo (rather than directly at the root level of your repo), specify the directory path that points to where the app code is located. (For the demo app in the previous section above, the directory path would be demo_app from this current repo.)

5. For the Docker image, the name is civisanalytics/civis-services-streamlit, and the tag is one of those listed on DockerHub. Note that the specific Docker image name and tag you've chosen determines which Python version your app is going to run on.

Support

For feature inquiries, bug reports, and other questions, Civis client users should reach out to [email protected].

Changelog

See CHANGELOG.md.

License

BSD-3

See LICENSE.txt.