{% endcomment %}
# "Introduction":#introduction
+# "Install dependencies":#dependencies
# "Set up database":#database-setup
# "Update config.yml":#update-config
# "Update nginx configuration":#update-nginx
-# "Install packages":#install-packages
+# "Install arvados-api-server and arvados-controller":#install-packages
+# "Confirm working installation":#confirm-working
h2(#introduction). Introduction
!(full-width){{site.baseurl}}/images/proxy-chain.svg!
-h2(#database-setup). Set up database
+h2(#dependencies). Install dependencies
+
+# "Install PostgreSQL":install-postgresql.html
+# "Install Ruby and Bundler":ruby.html
+# "Install nginx":nginx.html
+# "Install Phusion Passenger":https://www.phusionpassenger.com/docs/tutorials/deploy_to_production/installations/oss/ownserver/ruby/nginx/
-"On the node that will host the database, install PostgreSQL":install-postgresql.html .
+h2(#database-setup). Set up database
{% assign service_role = "arvados" %}
{% assign service_database = "arvados_production" %}
<notextile>
<pre><code> SystemRootToken: <span class="userinput">"$system_root_token"</span>
ManagementToken: <span class="userinput">"$management_token"</span>
- API:
- RailsSessionSecretToken: <span class="userinput">"$rails_secret_token"</span>
+ Collections:
+ BlobSigningKey: <span class="userinput">"$blob_signing_key"</span>
</code></pre>
</notextile>
-@SystemRootToken@ is used by Arvados system services to authenticate as the system (root) user when communicating with the API server.
-
-@ManagementToken@ is used to authenticate access to system metrics.
+These secret tokens are used to authenticate messages between Arvados components.
+* @SystemRootToken@ is used by Arvados system services to authenticate as the system (root) user when communicating with the API server.
+* @ManagementToken@ is used to authenticate access to system metrics.
+* @Collections.BlobSigningKey@ is used to control access to Keep blocks.
-@API.RailsSessionSecretToken@ is required by the API server.
-
-You can generate a random token for each of these items at the command line like this:
+Each token should be a string of at least 50 alphanumeric characters. You can generate a suitable token with the following command:
<notextile>
-<pre><code>~$ <span class="userinput">tr -dc 0-9a-zA-Z </dev/urandom | head -c50; echo</span>
+<pre><code>~$ <span class="userinput">tr -dc 0-9a-zA-Z </dev/urandom | head -c50 ; echo</span>
</code></pre>
</notextile>
<notextile>
<pre><code> Services:
Controller:
- ExternalURL: <span class="userinput">"https://xxxxx.example.com"</span>
+ ExternalURL: <span class="userinput">"https://ClusterID.example.com"</span>
InternalURLs:
- <span class="userinput">"http://xxxxx.example.com:8003": {}</span>
+ <span class="userinput">"http://localhost:8003": {}</span>
RailsAPI:
# Does not have an ExternalURL
InternalURLs:
- <span class="userinput">"http://xxxxx.example.com:8004": {}</span>
+ <span class="userinput">"http://localhost:8004": {}</span>
</code></pre>
</notextile>
-Replace @xxxxx.example.com@ with the hostname that you previously selected for the API server.
+Replace @ClusterID.example.com@ with the hostname that you previously selected for the API server.
The @Services@ section of the configuration helps Arvados components contact one another (service discovery). Each service has one or more @InternalURLs@ and an @ExternalURL@. The @InternalURLs@ describe where the service runs, and how the Nginx reverse proxy will connect to it. The @ExternalURL@ is how external clients contact the service.
h2(#update-nginx). Update nginx configuration
-Create a new file @/etc/nginx/conf.d/arvados-api-and-controller.conf@ . Configuration options that need attention are marked with "TODO".
+Use a text editor to create a new file @/etc/nginx/conf.d/arvados-api-and-controller.conf@ with the following configuration. Options that need attention are marked in <span class="userinput">red</span>.
<notextile>
-<pre><code>
-proxy_http_version 1.1;
+<pre><code>proxy_http_version 1.1;
# When Keep clients request a list of Keep services from the API
# server, use the origin IP address to determine if the request came
# "available keep services" request with either a list of internal keep
# servers (0) or with the keepproxy (1).
#
-# TODO: Following the example here, update the netmask to the
-# your internal subnet.
+# <span class="userinput">Following the example here, update the 10.20.30.0/24 netmask</span>
+# <span class="userinput">to match your private subnet.</span>
+# <span class="userinput">Update 1.2.3.4 and add lines as necessary with the public IP</span>
+# <span class="userinput">address of all servers that can also access the private network to</span>
+# <span class="userinput">ensure they are not considered 'external'.</span>
geo $external_client {
default 1;
+ 127.0.0.0/24 0;
<span class="userinput">10.20.30.0/24</span> 0;
+ <span class="userinput">1.2.3.4/32</span> 0;
}
# This is the port where nginx expects to contact arvados-controller.
upstream controller {
- server 127.0.0.1:8003 fail_timeout=10s;
+ server localhost:8003 fail_timeout=10s;
}
server {
# This configures the public https port that clients will actually connect to,
# the request is reverse proxied to the upstream 'controller'
- listen <span class="userinput">[TODO: replace with your public IP address]</span>:443 ssl;
- server_name <span class="userinput">[TODO: replace with the api server hostname]</span>;
+ listen 443 ssl;
+ server_name <span class="userinput">ClusterID.example.com</span>;
- ssl on;
- ssl_certificate <span class="userinput">/TODO/YOUR/PATH/TO/cert.pem</span>;
- ssl_certificate_key <span class="userinput">/TODO/YOUR/PATH/TO/cert.key</span>;
+ ssl_certificate <span class="userinput">/YOUR/PATH/TO/cert.pem</span>;
+ ssl_certificate_key <span class="userinput">/YOUR/PATH/TO/cert.key</span>;
# Refer to the comment about this setting in the passenger (arvados
# api server) section of your Nginx configuration.
client_max_body_size 128m;
location / {
- proxy_pass http://controller;
- proxy_redirect off;
- proxy_connect_timeout 90s;
- proxy_read_timeout 300s;
-
- proxy_set_header X-Forwarded-Proto https;
- proxy_set_header Host $http_host;
+ proxy_pass http://controller;
+ proxy_redirect off;
+ proxy_connect_timeout 90s;
+ proxy_read_timeout 300s;
+ proxy_max_temp_file_size 0;
+ proxy_request_buffering off;
+ proxy_buffering off;
+ proxy_http_version 1.1;
+
+ proxy_set_header Host $http_host;
+ proxy_set_header Upgrade $http_upgrade;
+ proxy_set_header Connection "upgrade";
proxy_set_header X-External-Client $external_client;
- proxy_set_header X-Real-IP $remote_addr;
- proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+ proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+ proxy_set_header X-Forwarded-Proto https;
+ proxy_set_header X-Real-IP $remote_addr;
}
}
# This configures the Arvados API server. It is written using Ruby
# on Rails and uses the Passenger application server.
- listen 127.0.0.1:8004;
+ listen <span class="userinput">localhost:8004</span>;
server_name localhost-api;
root /var/www/arvados-api/current/public;
index index.html index.htm index.php;
passenger_enabled on;
- # If you're using RVM, uncomment the line below.
- #passenger_ruby /usr/local/rvm/wrappers/default/ruby;
+ passenger_preload_bundler on;
# This value effectively limits the size of API objects users can
# create, especially collections. If you change this, you should
</code></pre>
</notextile>
-h2(#install-packages). Install packages
+{% assign arvados_component = 'arvados-api-server arvados-controller' %}
-Step 1: "Install Ruby and Bundler":ruby.html
+{% include 'install_packages' %}
-Step 2: "Install Nginx and Phusion Passenger":https://www.phusionpassenger.com/library/walkthroughs/deploy/ruby/ownserver/nginx/oss/install_passenger_main.html.
+{% assign arvados_component = 'arvados-controller' %}
-Step 3: Install arvados-api-server and arvados-controller
+{% include 'start_service' %}
-h3. Debian and Ubuntu
+h2(#confirm-working). Confirm working installation
-<notextile>
-<pre><code>~$ <span class="userinput">sudo apt-get install bison build-essential libcurl4-openssl-dev git arvados-api-server arvados-controller</span>
-</code></pre>
-</notextile>
+We recommend using the "Cluster diagnostics tool.":diagnostics.html The first few tests (10, 20, 30) will succeed if you have a working API server and controller. Of course, tests for services that you have not yet installed and configured will fail.
-h3. Centos 7
+Here are some other checks you can perform manually.
-<notextile>
-<pre><code>~$ <span class="userinput">sudo yum install bison make automake gcc gcc-c++ libcurl-devel git arvados-api-server arvados-controller</span>
-</code></pre>
-</notextile>
+h3. Confirm working controller
-h2. Confirm working installation
+<notextile><pre><code>$ curl https://<span class="userinput">ClusterID.example.com</span>/arvados/v1/config
+</code></pre></notextile>
-Confirm working controller:
+h3. Confirm working Rails API server
-<pre>
-$ curl https://xxxxx.example.com/arvados/v1/config
-</pre>
+<notextile><pre><code>$ curl https://<span class="userinput">ClusterID.example.com</span>/discovery/v1/apis/arvados/v1/rest
+</code></pre></notextile>
-Confirm working Rails API server:
+h3. Confirm that you can use the system root token to act as the system root user
-<pre>
-$ curl https://xxxxx.example.com/discovery/v1/apis/arvados/v1/rest
-</pre>
+<notextile><pre><code>$ curl -H "Authorization: Bearer $system_root_token" https://<span class="userinput">ClusterID.example.com</span>/arvados/v1/users/current
+</code></pre></notextile>
-Confirm that you can use the system root token to act as the system root user:
+h3. Troubleshooting
-<pre>
-$ curl -H "Authorization: Bearer $system_root_token" https://xxxxx.example.com/arvados/v1/users/current
-</pre>
+If you are getting TLS errors, make sure the @ssl_certificate@ directive in your nginx configuration has the "full certificate chain":http://nginx.org/en/docs/http/configuring_https_servers.html#chains
-h2. Troubleshooting
+Logs can be found in @/var/www/arvados-api/current/log/production.log@ and using @journalctl -u arvados-controller@.
-See the admin page on "Logging":{{site.baseurl}}/admin/logging.html .
+See also the admin page on "Logging":{{site.baseurl}}/admin/logging.html .