Skip to content
This repository has been archived by the owner on Jan 15, 2020. It is now read-only.

Latest commit

 

History

History
102 lines (72 loc) · 5.83 KB

installation.md

File metadata and controls

102 lines (72 loc) · 5.83 KB
Raw

Getting Started

System Requirements

You will need a server or virtual machine with (minimum) Windows Server 2016 or 2019 (LTSC) installed is recommended. It's possible to run Compute on a Windows 10 machine, but this is only recommended for development and testing.

It's still Rhino running under the hood, albeit without the UI, so spec your machine(s) accordingly. AWS's t2.medium instance type (2 vCPU, 4 GB RAM) is a great starting point.

The machine can be totally fresh. Everything else is described in the Installation and Configuration sections below.

"Installation"

The following steps assume that you are either logged into the computer that will run Compute, or connected via Remote Desktop. Currently there is no "installer", but these are the steps to get things running!

  1. Get the latest build from the master branch (the one named compute-<build_number>.zip). Alternatively you can build from source.
  2. Unzip everything into an empty directory, e.g. C:\path\to\compute.
  3. Download and install the latest Rhino WIP.
  4. Run Rhino at least once so that you can configure the license (we recommend Cloud Zoo) and validate it.
  5. Start PowerShell, cd C:\path\to\compute and run & .\compute.frontend.exe.
  6. Open a browser and try navigating to http://localhost/version.
  7. Hit Ctrl+C to stop Compute
  8. For next steps, see Configuration and Running Compute as a service.

Configuration

Calling Compute from another computer

Release builds of Compute listen on 0.0.0.0 by default so that you can connect from another computer. For this to work, you'll need to open ports in the Windows firewall. You may also need to configure URL reservation. The steps below assume you're using ports 80 for HTTP and 443 for HTTPS. If you're using another port, then you probably know what you're doing!

  1. Start PowerShell as Administrator
  2. Run Install-WindowsFeature -name Web-Server -IncludeManagementTools to install IIS and automatically open ports 80 and 443
  3. Configure URL reservation:
    1. For HTTP, netsh http add urlacl url="http://+:80/" user="Everyone"
    2. For HTTPS, netsh http add urlacl url="https://+:443/" user="Everyone"

Environment variables

All configuration of Compute – ports, authentication, etc. – is done via environment variables. See environment variables for details

HTTPS (optional)

HTTPS requires an SSL certificate. If you don't have one already, we recommend using Let's Encrypt.

  1. Configure a your domain name (e.g. compute.example.com) to point to your server's IP address
  2. Download win-acme and unzip
  3. Start PowerShell as Administrator
  4. Run Install-WindowsFeature -name Web-Server -IncludeManagementTools to install IIS (if you haven't already)
  5. cd to unzipped directory
  6. & .\wacs.exe
  7. N create new certificate
  8. 4 manually input host names
  9. compute.example.com (or similar)
  10. 1 for default web site
  11. Enter your email address when prompted
  12. yes to accept the license agreement
  13. Q to Quit

Running Compute as a service

Compute uses TopShelf to make it easy to configure and run it as a service on Windows.

  1. Start PowerShell as Administrator
  2. Run cd path\to\Release\
  3. Run & .\compute.frontend install to install as a service
  4. In the interactive menu, enter your username in the format .\\[USERNAME] (for example:.\steve) along with password for this account
  5. ⚠️ Important! Make sure to run Rhino (and configure the license) at least once as the user that the service will run as!

Scaling when using the Cloud Zoo

Rhino WIP encrypts Cloud Zoo license information by default. In order to create an image and scale your compute service you may need to disable encryption of the license information before creating your machine image. This is also a requirement for creating a Docker image.

  1. Open Rhino on the template machine (or host machine, in the case of Docker)
  2. From the Tools menu, click Options then click Advanced
  3. Search for Rhino.LicensingSettings.CloudZooPlainText
  4. Select the checkbox to enable the plain text setting
  5. ⚠️ Important! Close all instances of Rhino – changes do not take effect until Rhino is restarted
  6. Start Rhino
  7. Log back in to your Rhino Account
  8. Close Rhino

You can now create your machine image.

Building from source and debugging

  1. Download and install the latest Rhino WIP.
  2. Start Rhino WIP at least once to configure its license.
  3. Open src\compute.sln in Visual Studio 2017 (or later) and compile as Debug.
  4. In Solution Explorer, right-click Solution 'compute', then click Properties.
  5. In the Startup Project tab, select Multiple Startup Projects, then set both compute.frontend and compute.geometry to Start.
  6. Start the application in the debugger.
  7. Wait for the backend to load... ☕️ compute.geometry.exe
  8. Browse to http://localhost:8888/version to check that it's working!

Other things to note

  • The "frontend" is where the boring stuff lives – mostly authentication and request logging. The frontend proxies requests through to the "geometry backend". The backend is the bit that exposes a RESTful API that wraps functionality in RhinoCommon, Rhino.Python and Grasshopper.
  • There is a health check URL (/healthcheck) in case you want to set up a load balancer