X-Git-Url: https://git.arvados.org/arvados.git/blobdiff_plain/698f00b7f1c760f504963b42720c7fa2cbc66e48..3f0914ec893c01440778b01620776745da2546de:/doc/install/install-api-server.html.textile.liquid
diff --git a/doc/install/install-api-server.html.textile.liquid b/doc/install/install-api-server.html.textile.liquid
index ff877495de..e64c382669 100644
--- a/doc/install/install-api-server.html.textile.liquid
+++ b/doc/install/install-api-server.html.textile.liquid
@@ -1,164 +1,228 @@
---
layout: default
navsection: installguide
-title: Install the API server
+title: Install API server and Controller
...
+{% comment %}
+Copyright (C) The Arvados Authors. All rights reserved.
-h2. Prerequisites:
+SPDX-License-Identifier: CC-BY-SA-3.0
+{% endcomment %}
-# A GNU/Linux (virtual) machine
-# A domain name for your api server
+# "Introduction":#introduction
+# "Install dependencies":#dependencies
+# "Set up database":#database-setup
+# "Update config.yml":#update-config
+# "Update nginx configuration":#update-nginx
+# "Install arvados-api-server and arvados-controller":#install-packages
+# "Confirm working installation":#confirm-working
-h2(#dependencies). Install dependencies
-
-~$ sudo apt-get install libcurl3 libcurl3-gnutls libcurl4-openssl-dev \
- libxslt1.1 zlib1g-dev gettext bison libssl-dev libreadline-dev \
- libpq-dev sqlite3 libsqlite3-dev build-essential wget postgresql sudo
-
mkdir -p ~/src
-cd ~/src
-wget http://cache.ruby-lang.org/pub/ruby/2.1/ruby-2.1.2.tar.gz
-tar xzf ruby-2.1.2.tar.gz
-cd ruby-2.1.2
-./configure
-make
-sudo make install
-
-sudo gem install bundler
-
~$ cd $HOME # (or wherever you want to install)
-~$ git clone https://github.com/curoverse/arvados.git
-
~$ cd arvados/services/api
-~/arvados/services/api$ bundle install
-
~/arvados/services/api$ cp -i config/application.yml.example config/application.yml
-
SystemRootToken: "$system_root_token"
+ ManagementToken: "$management_token"
+ API:
+ RailsSessionSecretToken: "$rails_secret_token"
+ Collections:
+ BlobSigningKey: "blob_signing_key"
+
+
-Choose a unique 5-character alphanumeric string to use as your @uuid_prefix@. An example is given that generates a 5-character string based on a hash of your hostname. The @uuid_prefix@ is a unique identifier for your API server. It also serves as the first part of the hostname for your API server.
+@SystemRootToken@ is used by Arvados system services to authenticate as the system (root) user when communicating with the API server.
-For a development site, use your own domain instead of arvadosapi.com.
+@ManagementToken@ is used to authenticate access to system metrics.
-Make sure a clone of the arvados repository exists in @git_repositories_dir@:
+@API.RailsSessionSecretToken@ is required by the API server.
-~/arvados/services/api$ sudo mkdir -p /var/cache/git
-~/arvados/services/api$ sudo git clone --bare ../../.git /var/cache/git/arvados.git
-
~/arvados/services/api$ rake secret
-zzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzz
-
~$ tr -dc 0-9a-zA-Z </dev/urandom | head -c50; echo
+
+
-Put it in @config/application.yml@ in the production or common section:
+h3. PostgreSQL.Connection
secret_token: zzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzz
+ PostgreSQL:
+ Connection:
+ host: localhost
+ user: arvados
+ password: $postgres_password
+ dbname: arvados_production
~/arvados/services/api$ ruby -e 'puts rand(2**128).to_s(36)'
-6gqa1vu492idd7yca9tfandj3
-
Services:
+ Controller:
+ ExternalURL: "https://ClusterID.example.com"
+ InternalURLs:
+ "http://localhost:8003": {}
+ RailsAPI:
+ # Does not have an ExternalURL
+ InternalURLs:
+ "http://localhost:8004": {}
+
+
-Create a new database user with permission to create its own databases.
+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
+
+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 red.
+
+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
+# from the internal subnet or it is an external client. This sets the
+# $external_client variable which in turn is used to set the
+# X-External-Client header.
+#
+# The API server uses this header to choose whether to respond to a
+# "available keep services" request with either a list of internal keep
+# servers (0) or with the keepproxy (1).
+#
+# Following the example here, update the 10.20.30.0/24 netmask
+# to match your private subnet.
+# Update 1.2.3.4 and add lines as necessary with the public IP
+# address of all servers that can also access the private network to
+# ensure they are not considered 'external'.
+
+geo $external_client {
+ default 1;
+ 127.0.0.0/24 0;
+ 10.20.30.0/24 0;
+ 1.2.3.4/32 0;
+}
+
+# This is the port where nginx expects to contact arvados-controller.
+upstream controller {
+ 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 *:443 ssl;
+ server_name xxxxx.example.com;
+
+ ssl on;
+ ssl_certificate /YOUR/PATH/TO/cert.pem;
+ ssl_certificate_key /YOUR/PATH/TO/cert.key;
+
+ # 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_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;
+ }
+}
+
+server {
+ # This configures the Arvados API server. It is written using Ruby
+ # on Rails and uses the Passenger application server.
+
+ listen localhost:8004;
+ server_name localhost-api;
+
+ root /var/www/arvados-api/current/public;
+ index index.html index.htm index.php;
+
+ passenger_enabled on;
+
+ # If you are using RVM, uncomment the line below.
+ # If you're using system ruby, leave it commented out.
+ #passenger_ruby /usr/local/rvm/wrappers/default/ruby;
+
+ # This value effectively limits the size of API objects users can
+ # create, especially collections. If you change this, you should
+ # also ensure the following settings match it:
+ # * `client_max_body_size` in the previous server section
+ # * `API.MaxRequestSize` in config.yml
+ client_max_body_size 128m;
+}
+
+~/arvados/services/api$ sudo -u postgres createuser --createdb --encrypted --pwprompt arvados
-[sudo] password for you: yourpassword
-Enter password for new role: paste-password-you-generated
-Enter it again: paste-password-again
-Shall the new role be a superuser? (y/n) n
-Shall the new role be allowed to create more new roles? (y/n) n
-
~/arvados/services/api$ cp -i config/database.yml.sample config/database.yml
-~/arvados/services/api$ edit config/database.yml
-
~/arvados/services/api$ RAILS_ENV=development bundle exec rake db:setup
-
~/arvados/services/api$ cp -i config/initializers/omniauth.rb.example config/initializers/omniauth.rb
+$ curl https://ClusterID.example.com/arvados/v1/config
-Edit @config/initializers/omniauth.rb@. Set @APP_SECRET@ to the value of @app_secret@ from "installing the single sign on server":install-sso.html .
-
-You can now run the development server:
+Confirm working Rails API server:
-
-~/arvados/services/api$ bundle exec rails server --port=3030
+$ curl https://ClusterID.example.com/discovery/v1/apis/arvados/v1/rest
-h3. Apache/Passenger (optional)
-
-You can use "Passenger":https://www.phusionpassenger.com/ for deployment. Point it to the services/api directory in the source tree.
-
-To enable streaming so users can monitor crunch jobs in real time, add to your Passenger configuration in Apache:
+Confirm that you can use the system root token to act as the system root user:
-
-PassengerBufferResponse off
-
-
+
+$ curl -H "Authorization: Bearer $system_root_token" https://ClusterID.example.com/arvados/v1/users/current
+
-h2(#admin-user). Add an admin user
+h3. Troubleshooting
-Point your browser to the API server's login endpoint:
+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
-
-https://localhost:3030/login
-
-
-
-Log in with your google account.
-
-Use the rails console to give yourself admin privileges:
+Logs can be found in @/var/www/arvados-api/current/log/production.log@ and using @journalctl -u arvados-controller@.
-
-~/arvados/services/api$ bundle exec rails console
-irb(main):001:0> Thread.current[:user] = User.all.select(&:identity_url).last
-irb(main):002:0> Thread.current[:user].is_admin = true
-irb(main):003:0> Thread.current[:user].update_attributes is_admin: true, is_active: true
-irb(main):004:0> User.where(is_admin: true).collect &:email
-=> ["root", "your_address@example.com"]
-
+See also the admin page on "Logging":{{site.baseurl}}/admin/logging.html .