How to deploy an ADF APP

cancel
Showing results for 
Search instead for 
Did you mean: 

How to deploy an ADF APP

eugenio_romano
Alfresco Employee
1 18 18K

This document describes how to deploy an ADF Angular app.

Production build and Development build

The first task before to deploy your project is to produce a distribution build. Move to the main folder of your project before proceeding.

 

Development build

The result of this build is not optimized for production. The total sizes of the bundles are big because they contain unused code and have not been minified. However, this kind of build is useful in the development phase to debug your application.

  1. Run the build: 
       ng build

   This command will produce a dist folder in your project folder. If you want to change the output folder you can use the command :

  1.    ng build -op OUTPUT_FOLDER

Production build 

The result of this build is optimized for production. The total bundle sizes are smaller because the build makes use of a number of optimizations: AOT, Bundling, Minification, Uglification, and Dead code elimination. To learn more about this process please refer to the official Angular CLI documentation  build · angular/angular-cli Wiki · GitHub 

  1. Run the build: 
       ng build --prod

   This command will produce a dist folder in your project folder. If you want to change the output folder you can use the command :

  1.    ng build -op OUTPUT_FOLDER

Check the app.config.json file

Once the dist folder has been created it will contain the app.confg.json file that was originally in your main folder. Before proceeding with the deployment of your app, check that the configuration of app.config.json correctly targets your backend content services and/or process services.

See this document to find out how to set up different configurations for different environments: https://community.alfresco.com/people/eugenio_romano/blog/2018/03/07/how-to-organize-your-adf-appcon... 

Deploy the distribution

After your dist folder has been created, the next steps are:

  1. Copy the dist folder to your server
  2. Configure the server to fallback the routed app to index.html

The server fallback is needed to ask the server to return the index.html page when asked for a route or file that does not exist. These URLs will be interpreted by the Angular router

In the next part of this document we describe how to execute the two steps above for different server types:

  1. Apache
  2. NGinx
  3. GitHub Pages
  4. Firebase hosting

1. Apache

  1. Download Apache Tomcat from Apache Tomcat® - Apache Tomcat 9 Software Downloads 
  2. Copy the dist folder to the "webapps" folder of the Tomcat server.
  3. Open your conf/server.xml and add the following XML in the host tag: 
                <Context path="/" docBase="dist">
                  <WatchedResource>WEB-INF/web.xml</WatchedResource>
                </Context>‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍

  4. Start your Tomcat server

2. NGinx

  1. Install NGinx: Install | NGINX 
  2. Copy the dist folder to the default NGINX folder "/usr/share/nginx/html" (note that this folder may be different for your NGINX installation )
  3. Edit your /etc/nginx/nginx.conf file:

    worker_processes 1;

    events {
    worker_connections 1024;
    }

    http {
    server {
    listen 80;
    server_name localhost;

    root /usr/share/nginx/html;
    index index.html index.htm;
    include /etc/nginx/mime.types;

    gzip on;
    gzip_min_length 1000;
    gzip_proxied expired no-cache no-store private auth;
    gzip_types text/plain text/css application/json application/javascript application/x-javascript text/xml application/xml application/xml+rss text/javascript;

    location / {
    try_files $uri $uri/ /index.html;
    }
    }
    }
    ‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍

  4. Start the NGINX server

3. GitHub Pages

  1. Create a Github repository to store your project
  2. Install angular-cli-ghpages in your project with the command:  npm install -g angular-cli-ghpages
  3. Build the project with the base-href set to point to your repository: ng build --prod --base-href https://<username>.github.io/<reponame>/
  4. Publish the application: ngh -no-silent 
  5. Navigate to https://<username>.github.io/<reponame>/ 

4. Firebase hosting

  1. Create an account on firebase
  2. Create an app from https://console.firebase.google.com/
  3. Note your app has now an ID in this case my-new-project-7e300 . You will need this value later to deploy the app
  4. Install the firebase tools: npm install -g firebase-tools
  5. Login to firebase: firebase login
  6. Run the command: firebase init
    • Select  ❯ ◉ Hosting: Configure and deploy Firebase Hosting sites
    • Select a default Firebase project for this directory: [create a new project]
  7. The init command will create two new files: .firebaserc and firebase.json
  8. Run the command: firebase use --add my-new-project-7e300   
    (Note my-new-project-7e300 is the same id created above)
  9. Deploy your app : firebase deploy
  10. Open your app:  firebase open hosting:site

CORS

If you experience cross-domain requests problems then check this guide for advice on how to solve them: https://community.alfresco.com/community/application-development-framework/blog/2017/06/20/adf-cors-...

If you have any questions then feel free to reply here or contact us using gitter   .

18 Comments
angelborroy
Alfresco Employee

What’s your recommendation for base-href? We’re using it for Docker Composition together with Alfresco and other services...

eugenio_romano
Alfresco Employee

base href tell the router where you have your in index.html , the default value is URL the root. If you have your app in the root leave it as it is without changing it

angelborroy
Alfresco Employee

And how do you configure an HTTP proxy to include an ADF App (root path) and Alfresco Repository (requires root path to use AOS)?

eugenio_romano
Alfresco Employee

The proxy configuration depends a lot on how you decide to deploy it (Apache, NGINX, ...) the simple way is:

  1. The app in the root so, for example, www.YOUR_DOMAIN.com
  2. The content service in www.YOUR_DOMAIN.com/alfresco/ 
  1. The process service in www.YOUR_DOMAIN.com/activiti

and after the proxy should do the redirect to the right server if they are not physically mounted in those paths, so for example (NGINX) :

location /alfresco/ {
    proxy_pass  http://www.YOUR_DOMANI.COM:8080/;
    proxy_next_upstream error timeout invalid_header http_500 http_502 http_503 http_504;
    proxy_redirect off;
    proxy_buffering off;
    proxy_set_header        Host            $host;
    proxy_set_header        X-Real-IP       $remote_addr;
    proxy_set_header        X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_pass_header  Set-Cookie;
}

location /activiti/ {
    proxy_pass  http://www.YOUR_DOMANI.com:9999/;
    proxy_next_upstream error timeout invalid_header http_500 http_502 http_503 http_504;
    proxy_redirect off;
    proxy_buffering off;
    proxy_set_header        Host            $host;
    proxy_set_header        X-Real-IP       $remote_addr;
    proxy_set_header        X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_pass_header  Set-Cookie;
}

 but as I told you above any server can be configured in different way

angelborroy
Alfresco Employee

Taking your sample as base, AOS only will work in www.YOUR_DOMAIN.com, but you are capturing this route by the app and you are not delivering the request to Alfresco. How to solve this scenario?

dvuika
Alfresco Employee

There might be a million of ways to configure proxy and redirection for your application needs. All those approaches slightly go out of the scope of this article, so I would recommend taking a book on NGINX as a prerequisite, or figuring out the best approach with your system administrator I would say

eugenio_romano
Alfresco Employee

Can you give me an example of URL where AOS redirect you on Alfresco?

angelborroy
Alfresco Employee

When Office is connecting back to Alfresco, URLs like this one are invoked:

https://github.com/angelborroy/alfresco-docker-201707-GA/blob/master/httpd/assets/alfresco-vhost.con...

So root path must be redirected to "alfresco" container in order to maintain AOS feature working.

eugenio_romano
Alfresco Employee

If you right configure the proxy/servrer to return the application's host page (index.html) when asked only for a file/route that it does not have.

You shouldn't have any problem in this case. you have the file _vti_inf.html that is provided by the server and should not fallback on the index.html

angelborroy
Alfresco Employee

Ok, so your approach is to study SharePoint protocol to identify and map in the proxy every request to path root, revisiting this mapping every time a new upgrade is coming.

Thanks!

angelborroy
Alfresco Employee

Sorry, just other use case we had in the past.

How to configure two different ADF applications responding to the same server name?

We used (again) the "base-href" approach, but probably it can be solved in any other way.

angelborroy
Alfresco Employee
eugenio_romano
Alfresco Employee

I guess the article that you posted, explain exactly what you need to do

angelborroy
Alfresco Employee

Ok, so using "base-href" is not evil and ADF will support the feature now and ever.

Thanks again!

dvuika
Alfresco Employee

Base-href is not an ADF feature, it's an HTML standard that has been around for years. HTML base tag 

eugenio_romano
Alfresco Employee

yes indeed is not evil at all Smiley Happy we use it as well

angelborroy
Alfresco Employee

Denys Vuika of course, but at least I reported one issue in ACA 1.2 because it was not supported by your application

https://github.com/Alfresco/alfresco-content-app/issues/229

Just trying to be sure that I was doing the things right.

mjw
Customer

Why do you suggest Apache Tomcat instead of Apache httpd if you just want to serve static files?