How to deploy Atlascine

This is a guide for installing and hosting your own Atlascine service for the first time.

The below instructions are best followed if you know how to navigate and edit files in the terminal. However, they are very detailed, and aim to guide a reader who does not know the terminal. Simply follow each step closely and sequentially and you might be successful! Note that these instructions periodically link to existing Nunaliit documentation which also provides verified step-by-step instructions. The whole install process typically takes around 25 minutes if you have the appropriate Linux distribution already set up (Ubuntu 18.04<).

If you would like to collaborate on a managed Atlascine platform, please contact us directly.

Downloads

In addition to the linux packages that you may need to download and install, Atlascine relies on two code packages:

• the Atlascine source code (based on Nunaliit) (35.4 MB), provided by GCRC
• the atlas template (0.89 MB), provided by the Geomedia Lab

These required downloads are presented to you at the appropriate time in the instructions below.

1. Installing Atlascine prerequisites

In order to install the Atlascine source code on your system, make sure you are using the most suitable Linux distribution: Ubuntu 18.04 or above. If you do not have this installed, see the following link for more guidance:

• GCRC/nunaliit_tutorial/wiki#step-1---download-linux-distribution-

The following documentation walks you through the installation of Java, Couch DB, ImageMagick. ffmpeg and a few tweaks to the settings on your Ubuntu 18.04 system.

• GCRC/nunaliit/wiki/Prerequisite-install-on-Ubuntu-18.04-LTS

When you are finished with the prerequisite installation, you can go ahead and install Atlascine, as described below.

2. Installing the Atlascine source code

Atlascine is based on Nunaliit, so you will need to install Nunaliit on your machine. The following steps have you link to a script which does this for you.

Inside a parent folder of your choice (here, we will make one called atlascine: mkdir atlascine), you will need to clone and install the Atlascine branch of Nunaliit:

• Enter the parent folder you made: cd atlascine
• Clone and install Atlascine's source code by entering the following command: curl -sL https://raw.githubusercontent.com/geomedialab/nunaliit-devops/main/additional_helper_scripts/install-nunaliit.sh -o install-nunaliit.sh && sed -i 's/\r//' install-nunaliit.sh && bash install-nunaliit.sh
• If after several minutes your build ended with BUILD SUCCESS, you may continue.

3. Configuring the atlas

• Still inside your atlascine folder (which should now contain a folder called nunaliit), clone this atlas template from Github to a new subfolder with a name of your choice (preferably a short name without any spaces and which can also provide a working title for your atlas):
  • git clone https://github.com/geomedialab/atlas-template.git <your atlas folder name>
• Enter this new atlas folder (cd <your atlas folder name>). Then configure your atlas:
  • ../nunaliit/bin/nunaliit config
    • Here, you will need to provide the following:
      • atlas name (it is best if you use the same name as the one you just used to name your atlas folder);
      • the Couch DB port number (the default is fine);
      • a name for your content database;
      • whether or not you wish to manually review online submissions to your atlas (this is not recommended for most atlases, unless you wish to require any and all content modifications to require manual approval by an admin);
      • a name for your submissions database (if you enabled the previous option);
      • and an admin username (the default is fine);
      • the admin user password;
      • the port number where your atlas will reside;
      • an optional Google Maps API key (if you plan on using WMTS basemaps by Google, for example)
• Then update your atlas. This will send the files contained inside your atlas folder to the database. Since this will be your first update, the command could take several minutes to complete:
  • ../nunaliit/bin/nunaliit update
• After doing this, you should be able to run your atlas using the run command (from inside your atlas folder, as with all nunaliit commands, you would need to point to you nunaliit file like so../nunaliit/bin/nunaliit run). The atlas should then be visible at localhost:[your-port-number] (the port number you indicated during configuration) in your web browser.

4. Make your atlas run as a service

To avoid needing to restart your atlas manually every time your machine shuts down for whatever reason, it's best to set up your atlas as a service. To do this:

• You can refer to these instructions, which ask you to do the following:
  • Inside your atlas folder, there should be a folder called extra. Enter that folder by typing cd extra, then:
  • sudo cp nunaliit-YOUR-ATLAS-NAME.service /etc/systemd/system/.
  • sudo systemctl enable nunaliit-YOUR-ATLAS-NAME
  • sudo systemctl start nunaliit-YOUR-ATLAS-NAME

❗ Note that if you need to edit a file in the terminal, you can use the command vi FILENAMEto open it in the Vim text editor. To add text to a filename once opened in Vim, navigate to where you want to add something and press i to then type in whatever needs adding. When you're done, press the escape key and then type :wq to save and exit the document.

5. Configuring your atlas for the web

• To make your atlas visible on the web, make sure you have an available domain name (example.com) and follow the step-by-step instructions listed here: https://github.com/GCRC/nunaliit/wiki/Proxying-Nunaliit-with-Apache2-and-SSL (note that these instructions apply to Ubuntu 18.04 as well)

  Note:

  • The port number that you indicate here should be the same as the one you used in the configuration steps indicating where your atlas resides

  • In the step where you are asked to create an apache config file, you may elect to instead paste the text indicated into a file called 001-rs-atlascine.concordia.ca-ssl.conf instead of 001-rs-atlascine.concordia.ca.conf,

  • If you have additional subdomains related to specific additional atlases, for example, then add RewriteEngine On above ProxyRequests Off in your apache config file. Rewrite rules for assigning a subdomain to a specific atlas and its port number can then be added below the </Proxy> tag in your apache config file like so:

    RewriteRule ^/slug$ /atlasfoldername/ [R]
    ProxyPass /atlasfoldername/ http://127.0.0.1:808X/
    ProxyPassReverse /atlasfoldername/ http://127.0.0.1:808X/
    

    You will also need to paste the following below the above and before the line starting with SSLCertificateFile

    ProxyPass / http://127.0.0.1:8080/
    ProxyPassReverse / http://127.0.0.1:8080/
    

6. Setting up the mail server

You will also need to set up the email server that will be used to send out email notifications to users regarding their content upload approvals and so on. This is especially important to do if you plan on managing an atlas with multiple users and content uploads and modifications.

To edit the mail server properties, inside your atlas folder, navigate to the config/ folder and then open the mail.properties folder.

• cd config and then vi mail.properties
• Your mail.properties file should look like this. Be sure to replace the example.com URLs with your own, add your own email and modify the areas marked by square brackets.
• After making the necessary changes to mail.properties, make sure to update your atlas (../nunaliit/bin/nunaliit update) and restart your atlas service (systemctl restart nunaliit-ATLASNAME.service) for the changes to take effect.