Installing the Developer Portal

In order to use the Developer Portal, you need to complete a one-time installation and setup process.

In order to install and set up the Developer Portal, complete the following steps.

1. Install the Developer Portal virtual appliance:
   1. The Developer Portal OVA is configured to use DHCP to obtain an IP address. If you choose to use DHCP, you might want to specify a MAC address, if your IP addresses are given out based on MAC addresses. This can be done in the OVA settings, and should be done before the machine is powered on for the first time. Alternatively, to use a static IP address, complete the following steps.
      1. Enter the following command to become the root user:

         sudo -i

      2. For Developer Portal versions 5.0.8.10-GA or earlier, on a Ubuntu16.04 base, edit the file /etc/network/interfaces, and configure the following entries:

         allow-hotplug eth0
         iface eth0 inet static
         address ip_address_of_virtual_appliance
         netmask subnet_mask_in_dotted_decimal_format
         gateway gateway_ip_address
         

         Where:

         ip_address_of_virtual_appliance is the IP address that you want to set for the virtual appliance, and gateway_ip_address is the IP address of your gateway.

         Note: You can use nano to edit the file.
         For Developer Portal version 5.0.8.10-iFix or later, on a Ubuntu18.04 base, edit the file /etc/netplan/00-installer-config.yaml, and configure the following entries:

         network:
           ethernets:
             eth0:
               dhcp4: no
               addresses: [ip_address_of_virtual_appliance/subnet_mask_in_cidr_notation]
               gateway4: gateway_ip_address
           version: 2

         Where:

         ip_address_of_virtual_appliance is the IP address that you want to set for the virtual appliance, and gateway_ip_address is the IP address of your gateway.  subnet_mask_in_cidr_notation is the shorthand number for the subnet mask, for example 192.168.10.0/24 is equal to the network 192.168.10.0 with a 255.255.255.0 subnet mask.
      3. Configure the following entries depending on whether you are installing your Developer Portal OVA on a Debian or Ubuntu base.

         Installing on a Debian base

         Edit the file /etc/resolv.conf and configure the following entries:

         nameserver nameserver_ip_address_1
         nameserver nameserver_ip_address_2
         domain domain_name
         search domain_name

         Where:

         nameserver_ip_address_1 is the host name or IP address of the domain name server. Additional domain name servers are added on separate lines in the file.

         domain_name is the domain name that you want the machine to have.

         Installing on an Ubuntu 16.04 base

         Edit the file /etc/network/interfaces and configure the following entries:

         dns-search domain_name 
         dns-nameservers nameserver_ip_address_1 nameserver_ip_address_2

         Where:

         domain_name is the domain name that you want the machine to have.

         nameserver_ip_address_1 is the host name or IP address of the domain name server. Additional domain name servers are added on the same line but with one space in between.

         Installing on an Ubuntu 18.04 base for Developer Portal version 5.0.8.10-iFix or later

         Edit the file /etc/netplan/00-installer-config.yaml and configure the following entries:

         network:
           ethernets:
             eth0:
               dhcp4: no
               addresses: [ip_address_of_virtual_appliance/subnet_mask_in_cidr_notation]
               gateway4: gateway_ip_address
               nameservers:
                 addresses: [nameserver_ip_address_1, nameserver_ip_address_2]
                 search: [domain_name]
           version: 2

         Where:

         domain_name is the domain name that you want the machine to have.

         nameserver_ip_address_1 is the host name or IP address of the domain name server. Additional domain name servers are added on the same line but with a comma and a space in between.

      4. Configure the machine to detect the changes you have made.
         Installing on a Debian base:

         service networking restart
         ifup eth0

         Installing on an Ubuntu base:

         ifdown eth0 && ifup eth0

         Installing on an Ubuntu 18.04 base:

         netplan apply

         Note: you will still be logging into the CLI, but via the virtual appliance console, which can be accessed without the network card having an address. If your machine has picked up an automatic address from DHCP, SSH should be used to change it to static. If your changes are not being reflected, please try restarting the Developer Portal Machine.

         Note: For more information and configuration examples for netplan, see https://netplan.io/examples/.
      5. Exit the root shell:

         logout

      See Logging in to the CLI with a Secure Shell session connection for information on logging in to the virtual appliance using a secure shell connection.
2. Configure the Developer Portal in the Cloud Manager:
   1. Log in to the Cloud Manager as a cloud administrator.
   2. In the navigation section of the Cloud Manager, click the Settings icon . The Settings pane displays.
   3. In the Developer Portals section of the Settings pane, enable the Developer Portal by selecting the Enable the developer portal toggle. This setting allows the Developer Portal to be selected as the portal for any Catalogs that are created.
   4. Enter the virtual appliance host name or IP address in the Portal Management Address field. For more information, see Load balancing the requests the Cloud Manager sends to the Developer Portal.
   5. Ensure the port number, configured for the virtual appliance, in the Port field is set to 22.
      
      The API Manager communicates with the Developer Portal via SSH, which is on port 22 by default.

      Important: There is no support for presenting a client certificate when a call to /v1/portal/ is made.
   6. Copy the contents of the Public Key field and store the content so it is available for use in the next step.
      In the next step you will place this key onto the Developer Portal server to allow the API Manager to create an Developer Portal site for each Catalog that is created.
   7. Click Save in the Developer Portals section.
3. Configure the Developer Portal virtual appliance:
   1. Log in to the Developer Portal virtual appliance CLI with the following credentials:
      • User ID: admin
      • Password: !n0r1t5@C
        Note: This console uses a US keyboard configuration, in which the @ symbol can be in a different place to other keyboard configurations. If you are not using a US keyboard, please ensure that you have typed the password correctly.
      
      
      See Logging in to the CLI with a Secure Shell session connection for information on logging in to the virtual appliance using a secure shell connection.
   2. Enter the following commands:
      1. Create a file on the file system of the Developer Portal virtual appliance by copying and pasting the public key contents from the location you stored it in during the previous section:

         echo "contents_pasted_from_the_public_key_field" > key_file_name

         Where: key_file_name is the name of the file that will be created on the Developer Portal virtual appliance.
         Note: If you cannot paste your command into the console, you can ssh in with a client such as PuTTY, or use winscp to copy a file across with the relevant contents.
      2. Run the set_apim_host command to connect the Developer Portal to the Management cluster:

         cat key_file_name | set_apim_host devportal_fqdn apic_fqdn

         Where:
         • devportal_fqdn is the fully qualified domain name of the Developer Portal virtual appliance. If you are setting up a cluster, then each Developer Portal in the cluster must have a unique name.
         • apic_fqdn must be the same value as the address in the Management service on the APIC Cloud Manager.
         Important: You cannot use the IP address of your virtual machine as the devportal_fqdn in this command. For more information, see set_apim_host.
      3. Configure the SMTP server that will be used to send emails from the Developer Portal.

         set_smtp mail_server_host_name port user password

         Where:
         mail_server_host_name must resolve to the IP address of the mail server.
         port is the port to use when connecting to the SMTP server.
         If the SMTP server requires account information then:
         user is the user name to authenticate to the SMTP server.
         password is the password to authenticate the user with.

      If your SMTP server setup does not work after configuration with the set_smtp command, run the following command:

      sudo nano /etc/postfix/main.cf

      and change any values that your SMTP server requires. Then, save the file and run the follow commands to ensure that postfix is using the new values:

      sudo service postfix restart
      sudo postfix reload

4. Configure which languages are available in the Developer Portal.
   Edit the file ~/config/languages.txt.

   Each line of the file is a language code that is supported by the Developer Portal, remove any language codes that you do not require. Removing language codes will decrease server load, disk space used and the time taken to create a new Developer Portal for each Catalog.

   Note: English US is always available, all lines in the file are additional languages.
5. Note: You must complete only one of the following three options in this step for your installation to be successful.
   If you have installed a TLS certificate that is signed by a known Certificate Authority on the API Manager then the Developer Portal should already trust the API Manager. If not then you need to configure the Developer Portal to trust the API Manager node. This can be done automatically, manually or you can configure the Developer Portal to trust any TLS certificate; you can use one of the following commands for this depending on which of these ways you wish to configure your Developer Portal:
   • To automatically obtain the TLS certificate, enter the following command:

     download_apim_cert

     This causes the Developer Portal to contact the configured Management cluster, download the TLS certificate and add it to the Developer Portal trust store.
   • If you have a file that contains the TLS certificate and want to use this to configure trust, enter the following command:

     cat filename.crt | set_apim_cert -s

     Where:
     filename.crt is the name of the file that contains your TLS certificate (in PEM format) .
   • For proof of concept and testing, you can enter the following command:

     set_apim_cert -i

     This will cause the Developer Portal to trust any TLS certificate served by the API Connect node.

     Note: This should only be used for development and testing purposes as it is not secure and leaves the Developer Portal exposed to a man-in-the-middle attack.
6. Optional: Configure the Developer Portal to serve your own TLS certificate.
   Note: The Developer Portal can support only one TLS certificate, which can be a wildcard or multi-domain certificate. If you want to serve different TLS certificates for each site that is hosted on the Developer Portal, you must front the Developer Portal with a reverse proxy server.

   To serve different certificates for each site, the reverse proxy server must be configured to terminate the TLS for the connection to the Developer Portal.

   1. If you want the Developer Portal to serve your own TLS certificate, rather than the default, use the following steps. You will need two files with the following content:
      • myorg.key, which must contain the TLS private key in PEM format.
      • myorg.crt, which must contain the TLS certificate in PEM format.
   2. Enter the following commands:

      cat myorg.key | set_devportal_key  
      cat myorg.crt | set_devportal_cert             

      Note: If you are using a certificate chain, then the Developer Portal certificate file must be concatenated in the correct order:

      
      -----BEGIN CERTIFICATE-----
      Insert SSL Certificate
      -----END CERTIFICATE-----
      -----BEGIN CERTIFICATE-----
      Insert Intermediate Certificate
      -----END CERTIFICATE-----
      -----BEGIN CERTIFICATE-----
      Insert Root Certificate
      -----END CERTIFICATE-----

      Note:

      • You will see a validation error after entering the first command, this is because the new key does not match the old certificate. This error should resolve after you have entered the second command.
      • The process to renew SSL certificates is the same as the process to set up new ones.