Skip to content

Installations instructions

To install Apiro locally, you can make use of Docker Desktop and Docker Compose to install on your local machine. If and when you decide to install a permanent production instance of Apiro Community, you may make use of Apiro's official public compute images on popular cloud vendors such as AWS and Azure. Alternatively. for those with the technical capability and specific requirements, the Apiro Community Docker images are available publicly on DockerHub and may be installed using whatever custom deployment scenario you care to maintain (such as Kubernetes configurations) Commercial versions of Apiro are strictly to be installed into a Kubernetes cluster and may be lifecycle managed via an Apiro supplied Helm chart.

Minimum requirements

  • Windows

    • Windows 11
    • RAM 16GBs
    • Docker Desktop version 4.29

  • MacOs

    • MacOS Soroma 14.4.1
    • RAM 16GBs
    • Docker Desktop version 4.29
Installation Instructions
  1. Install and start Docker Desktop
  2. Pull the community version of Pull the community version of Apiro Community Compose Public from Git. Note: The community scripts may be updated regularly. It is strongly encouraged to pull from the origin regularly.
  3. Start Docker Desktop. The minimum required version for both Windows and MacOS is 4.29.
  4. Open your command line go to `/apiro-community-compose-public/'
  5. For MacOS run 
    1
        ./runapiro.sh v1 apiroexamples-pub clean
    and for Windows run 
    1
        ./runapiro.bat v1 apiroexamples-pub clean`

  6. Notes for Windows

    Note1: If you are getting MongoDB connection issues it means that the server is trying to connect to MongoDB before starting properly. This is common with slower machines. In order to fix this please uncomment this property and increase the value to 20 #APIRO_PREPAUSE=5 Note2: The script will attempt to bind to ports 8080, 8081 and 8082. If these ports are not available the script will fail to run. You must either make those ports available or specify other ports as described below. The Windows script was tested on Windows 11, Docker Desktop 4.29.0 utilising the WSL2 based engine (not the old Hyper-V based backend)

  7. Wait until you see the following APIRO COMPLETED AUTOINIT message in the command line you.

    Note When you see the AUTONIT COMPLETED SUCCCESSFULLY message it means, the server is running correctly even if the command line continues to print out messages.

  8. Go to http://127.0.0.1:8080/ and login using (username: admin, password: qwerty55!) installation

  9. You should be able to now navigate the examples described in the use guide.

  10. The instance is pre configured to boostrap using existing examples in apiro_examples git repository
  11. Please note that the instance is already setup with an existing git user apiropublic.
  12. However, you will not be able to write (create or edit schemas, feeds, dataSources or other entities) to this public repository or follow the Getting started guide.
  13. To terminate the server you need to type ctrl-c
  14. In order to to be able to complete the "Getting Started Guide" you need to create your own repository and follow the instructions below.
  15. Apiro allows you to bootstrap with 9 repos. Adding them as xml allows unlimited config source repos. An example will be provided soon in the Getting started guide.
Customize your instance to run against your own repository
  1. You will notice the file apiro-community-compose-public/apiro-apiroexamples-pub-properties.env
  2. Duplicate the file and name it apiro-community-compose-public/apiro-apiroexamples-copy-pub-properties.env
  3. replace the value of APIRO_ADMINEMAIL with a valid email you have access to.
  4. replace the value of APIRO_ADMINPW with your own non encoded password you want to use to login to Apiro after visiting http://127.0.0.1:8080/>
  5. replace the value of GIT1_NAME with the name of your repository. You can choose any name you want as this will be shown in the Apiro UI after it loads.
  6. set the value of GIT1_READONLY with false
  7. replace the value of GIT1_URL with the URL of your own private repository you have write access to.
  8. replace the value of GIT1_USER with your own git username that has access to GIT1_URL.
  9. replace the value of GIT1_PASS with the token you created for your own GIT user to access your own repository.
  10. replace the value of GIT1_BRANCH with the branch to intend to use to store the Apiro configuration files. It is acceptable to just use main.
  11. replace the value of GIT1_PREFIX with the path to the directory you want your configuration files to reside. It is acceptable to just use root GIT1_PREFIX=/.

  12. if any of the ports 8080, 8081, 8082, 27018 are not available you can replace the values of these properties accordingly - APIRO_WEB_PORT, - APIRO_REST_PORT, - APIRO_WS_PORT, - APIRO_MONGO_PORT. 

     1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
        # admin account details
    APIRO_ADMINPW=qwerty55!

    # REPLACE aaa@bbb.com WITH YOUR OWN VALID EMAIL
    APIRO_ADMINEMAIL=aaa@bbb.com

    #change the values below to reassign binding ports
    #APIRO_WEB_PORT=8080
    #APIRO_REST_PORT=8081
    #APIRO_WS_PORT=8082
    #APIRO_MONGO_PORT=27018

    # GIT system properties repository
    GIT1_NAME=APIRO_EXAMPLES
    GIT1_READONLY=true
    GIT1_URL=https://github.com/redapiro/apiro_examples.git
    GIT1_USER=apiropublic
    GIT1_PASS=[PREDEFINED_ENCODED_TOKEN_FOR_APIROPUBLIC]
    GIT1_BRANCH=version1
    GIT1_PREFIX=/config/


    # jvm opts
    JVM_OPTS="-Xmx4G -XX:+UseZGC -XX:+ZGenerational"

    RUNFEED_ON_START=ALL

    #enable quartz scheduler
    APIRO_QUARTZENABLED=true

    # mail server details - if you want to use email notifications
    APIRO_SMTP_ENABLED=false
    APIRO_SMTP_HOST=TODO
    APIRO_SMTP_HOST=TODO
    APIRO_SMTP_USER=TODO
    APIRO_SMTP_USER=TODO
    APIRO_SMTP_PASSWORD=TODO

  13. After you make the above changes you need to restart and login to apiro using the the new modified properties file. Note that the name of the file is different that then one mentioned at the top of this page. For MacOS run 

    1
    ./runapiro.sh v1 apiroexamples-copy-pub clean
    and for Windows run 
    1
    ./runapiro.bat v1 apiroexamples-copy-pub clean
    • Note about secrets:
      Apiro should never encode secrets and privileged information, such as API tokens in its configuration repositories. It therefore provides encryption and hashing facilities for this end. In addition to being able to access secret management and encryption APIs provided by the dominant plublic cloud utilities such as AWS, GCP and Azure, it has an inbuilt secrets vault called SYS Vault Manager, which uses symmetric key AES encryption to encrypt secrets. The user interface provides the facility to encrypt secrets via SYS (though for security purposes it's a one way process - there is no way to decrypt them via the UI or API). The relevant documention provides information on how to make use of the SYS Vault manager for general configuration. However, with regard to bootstrapping Apiro via environment variable settings (which is the subject at hand here), it is suffice to say that Apiro allows the GIT keys and/or passwords for the Configuration Sources to be provided in clear text or encrypted via SYS Vault Manager. We strongly recommend you make use of SYS to encrypt any privileged config information. To encrypt any string data via SYS follow these procedures below:

  14. You need to navigate to the Secret Management page as shown by the screenshot below

    Secret Management

    generate_secret

  15. Copy the current value of GIT1_PASS and generate the associated secret.

  16. Copy the secret and override the existing GIT1_PASS value.
  17. You also need to to provide your own GITHUB user credentials by updating the properties APIRO_GITHUB_USERNAME and APIRO_GITHUB_PW in SYSPROPS_GITHUB.xml file.
  18. After you modify the property files you need to push the changes to GIT and restart the server once again.

  19. This GIT user must have access to the repository you configured in the apiro-community-compose-public/apiro-apiroexamples-pub-properties.env file above.

    GIT user included used in Data Sources

    github_credentials

  20. Finally, this is an optional step and if you want to use the GPT and DocAi examples you need to update GCP_SVC_ACCOUNT_BASE64, GCP_SVC_ACCOUNT and OPENAI_API_KEY in SYSPROPS_AUTH.xml file.

    Setup credentials for GPT and DocAI examples

    gcp_openai_credentials

21 Restart Apiro. - Note: In accordance with common best practice SYS makes use of a random set of prelude characters, so the same string encrypted multiple times will never generate the same ciphertext - it will be different every time, including in total ciphertext length.

Go back to Getting started guide