Civis Service Deployment

Services make it easy for you to host web applications and introduce interactivity into your data science workflow. It allows your reports to access databases, run custom R or Python code, and respond to users in real time. Compute and memory resources are handled natively, so it’s easy for you to increase or decrease the resources your application uses on a case by case basis. If your app is very popular, you can even scale it up with only a few clicks. 

Server instances are managed by an auto-scaling cloud infrastructure, Docker containers handle environments and dependencies, and Civis Platform integrates with Git to handle your app’s code.

Getting Started

The quickest way to get started is with our Service Templates. Navigate to the Publish menu and launch either a Streamlit dashboard, a Shiny dashboard, or a Flask API service. From there you can clone their respective GitHub repositories to get started building your own.

Services Configuration Parameters

Git Connection

• Repository: The url for the git repo where the Service code lives. Example: https://github.com/<my_organization>/<my_repo>.git.  This code will be pulled into the /app directory.
• Branch: The git reference to use when pulling code from the repo. Can be a branch, commit hash or tag. If the app is on demand or scheduled, it will clone this reference when it wakes up so the reference should be stable.
• Path: The path to the Service code within the git repo. If unspecified, the root directory will be used.

Docker

• Image Name: The name of the docker image to pull. The image may be in any registry including: DockerHub, ECR, and Github Container Registry. Civis has made a default image available for Shiny apps: civisanalytics/civis-services-shiny.
• Tag: The tag of the docker image to pull. (default: latest).

Resources

• Memory (MB): The amount of memory in megabytes allocated to each replica of the Service.
• CPU (m): The amount of CPU allocated to each replica of the the Service. 1000 represents a single core, 2000 represents two cores, and so on.
  • Pro Tip: Don’t set this higher than 1000 (one core) unless your app makes use of a parallelization library.
• Replicas: The number of Service replicas to deploy. Each replica will run independently and will not share state. This may be useful for Services that require many users to view the Service at the same time.

Security and Access

• Credentials: A list of credential IDs to pass to the Service.

Start a Service/Preview a Deployment

After filling out the deployment configuration, you can start a Service deployment on the service page by clicking “Start Deployment.” A preview of the deployment will appear under "preview" on the service page. If the service fails to start within an hour of deployment, the service will be automatically terminated.

Scheduling

Once a Service is deployed, it runs on a schedule.  We provide three scheduling options so that you can control when your Service runs.  You are only charged for the resources consumed when the Service is running.

To view or change a Service’s schedule, press the “Multischedule” button on the top-right panel of the Service configuration page

Scheduling Options

• On Demand
• The deployed Service will switch between running and sleeping states depending on activity.  It will “sleep” (and not consume resources) after no one has viewed its configuration page or its report for an hour.  It will “wake up” (and start consuming resources) once a user views either the configuration page or the report.
• Specific Times
• The deployed Service will stay running during the times specified in the UI and will start up quickly for end users during these times. Outside of these times, the Service will perform “on demand,” and the end user will experience a slower startup time.
• Always On
• The deployed Service will always be on. This means that it will be consuming resources even when it isn’t being used, but it will always start up quickly for end users. Note that the service will be redeployed once per week in order to optimize usage of your compute instances and provide it with a new API key. This redeployment happens with no downtime for the app.

Publish to Report

To see the actual report/app that you launched, click “View Report.”

You will be redirected to a new URL that looks like:

https://platform.civisanalytics.com/#/reports/services/<some number>?fullscreen=true 

This URL can be accessed by anyone who has been shared on the deployed report. The report will be automatically shared with your default group in Civis Platform. To access and adjust report sharing settings, toggle the report out of full-screen mode and click the Sharing icon. 

A published Service is running and will consume resources until it is manually or automatically stopped or sleeping.

Update Deployment

While a Service is deployed, the deployment can be updated to the latest code without stopping the deployment by clicking on “Update Deployment.”

Updating a Service’s deployment will refresh the configuration settings and API Key, and it will initiate a code pull from Git.

Understanding the Status of Your Service

Service status can be found on the index page. Services can be stopped, asleep, or awake.

• Stopped
• A stopped Service is not running, and its report cannot be viewed by end users. It does not consume computing resources. A stopped Service can only be started by a user who has “Editor” sharing permissions on the Service.
• Sleeping 
• A sleeping Service is not running, but it is available to be viewed by the end user. It does not consume computing resources. When a sleeping Service is accessed, it requires extra time to “wake up” before it can be used.
• When a sleeping Service wakes up, its API key is refreshed and it initiates a code pull from Git, but any changes to the configuration settings are not recognized. To implement changes in a Service’s configuration settings, the Service’s deployment must be updated.
• Running 
• A Service is running when it is available for immediate viewing by an end user. A running Service consumes computing resources.

Deployment History

Similar to Run History in Scripts, a Service’s Deployment History can be accessed from the top of the Service’s Deploy page.

Deployment history includes deployment logs as well as metadata about the deployment.

Deployment logs for services tend to be very long, and can slow down or even crash your browser when viewed in full. For this reason, we recommend using the custom logs feature. You can select a custom length for your log history in minutes, hours or days.

Dependencies

Civis has created a set of pre-built Docker images which contain many of the standard packages used in data science projects to make building apps easier. Many Services can rely on these prebuilt images to handle their dependencies. For those that need additional dependencies, Services implements a flexible workflow to add dependencies on top of the pre-built images and to create a new Docker image altogether for full customizability.

If extra dependencies for a Service are required, they can be installed in one of the following ways:

• Finding an existing open source Docker image either from Civis or from a trusted third party with the necessary dependencies.
• Using a framework with a method for executing code before the server runs.  For example, 
  
• Include in your services code a two step process of 1) install and then 2) run the server.
• Use a custom Docker image which includes the necessary dependencies. This is the most advanced and flexible option.

If your Civis Platform profile includes Github Credentials, a Github token will be automatically inserted into your service as the environmental variable REPO_HTTP_TOKEN. You can use this token to download private repositories from Github.

Special Note About R Shiny

All R Shiny applications deployed in Civis Platform need a couple tweaks to keep them from disconnecting.  See the Shiny App Deployments for more information.

FAQ

• My Service has dependencies on code that is private. How can I include these dependencies in my Service?
  • You can include private dependencies by adding them as git submodules to your project, or you may install them in a custom Docker image and configure your Service to use this Docker image rather than the default. 

• When I try to publish or preview my Service, all I see is a spinner or a grey screen. How can I fix this?
  • If your Service fails to load when previewing or publishing, your Service may not be running correctly in the specified Docker container. Double check the logs to see if there are any helpful error messages. Often your Service will run locally but fail when trying to preview it on Platform if your Service has special dependencies that were not specified.
  • Your Service might also be running on the wrong port.  By default, Services must respond to web requests on port 3838.  See Advanced Deployments.

• My Service is taking a long time to start, how can I speed it up?
  • All Services will take some time on their first launch to load as they need to download the Docker repository and your code. Custom Docker images will take longer than usual, as they don’t benefit from the caching we do with our default Docker images.
  • “Always On” isn’t set to True. This configuration allows your Services to remain on at all times and will dramatically speed up load time for viewers.  When set to False, your Service may go to sleep (preserving resources) and will take some time to relaunch from a sleeping state.
  • You may have long running code in your Service.  You can greatly speed up your Service if you implement caching or if you put all of your one-time long running code in a setup step that only runs once when your app launches.
  • There are a number of other potential reasons why a Service may take some time to load.  The deployment logs should give you some insight into what is happening.