source: gs3-extensions/maori-lang-detection/hdfs-cc-work/GS_README.TXT@ 33539

----------------------------------------
INDEX: follow in sequence
----------------------------------------
A.  VAGRANT VM WITH HADOOP AND SPARK
B.  Create IAM role on Amazon AWS to use S3a
C.  Configure Spark on your vagrant VM with the AWS authentication details
---
Script scripts/setup.sh now is automated to do the steps in D-F below
and prints out the main instruction for G.
---
D.  OPTIONAL? Further configuration for Hadoop to work with Amazon AWS
E.  Setup cc-index-table git project
F.  Setup warc-to-wet tools (git projects)
G.  Getting and running our scripts
----------------------------------------

----------------------------------------
A. VAGRANT VM WITH HADOOP AND SPARK
----------------------------------------
Set up vagrant with hadoop and spark as follows

1. by following the instructions at
https://github.com/martinprobson/vagrant-hadoop-hive-spark

This will eventually create the following folder, which will contain Vagrantfile
/home/<USER>/vagrant-hadoop-hive-spark

2. If there are other vagrant VMs set up according to the same instructions on the same machine, then need to change the forwarded ports (the 2nd column of ports) in the file "Vagrantfile". In the example below, excerpted from my Vagrantfile, I've incremented the forwarded ports by 1:

    config.vm.network "forwarded_port", guest: 8080, host: 8081
    config.vm.network "forwarded_port", guest: 8088, host: 8089
    config.vm.network "forwarded_port", guest: 9083, host: 9084
    config.vm.network "forwarded_port", guest: 4040, host: 4041
    config.vm.network "forwarded_port", guest: 18888, host: 18889
    config.vm.network "forwarded_port", guest: 16010, host: 16011

Remember to visit the adjusted ports on the running VM.

3. The most useful vagrant commands:
vagrant up      # start up the vagrant VM if not already running.
            # May need to provide VM's ID if there's more than one vagrant VM
ssh vagrant     # ssh into the sole vagrant VM, else may need to provide vagrant VM's ID

vagrant halt    # to shutdown the vagrant VM. Provide VM's ID if there's more than one vagrant VM.

(vagrant destroy)   # to get rid of your vagrant VM. Useful if you've edited your Vagrantfile


4. Inside the VM, /home/<USER>/vagrant-hadoop-hive-spark will be shared and mounted as /vagrant
Remember, this is the folder containing Vagrantfile. It's easy to use the shared folder to transfer files between the VM and the actual machine that hosts it.

5. Install EMACS, FIREFOX AND MAVEN on the vagrant VM:
Start up vagrant machine ("vagrant up") and ssh into it ("ssh vagrant") if you haven't already.


a. sudo apt-get -y install firefox

b. sudo apt-get install emacs

c. sudo apt-get install maven
  (or sudo apt update
   sudo apt install maven)

Maven is needed for the commoncrawl github projects we'll be working with.


6. Although you can edit the Vagrantfile to have emacs and maven automatically installed when the vagrant VM is created, for firefox, you're advised to install it as above.

To be able to view firefox from the machine hosting the VM, use a separate terminal and run:
   vagrant ssh -- -Y
[or "vagrant ssh -- -Y node1", if VM ID is node1]

READING ON Vagrant:
    * Guide: https://www.vagrantup.com/intro/getting-started/index.html
    * Common cmds: https://blog.ipswitch.com/5-vagrant-commands-you-need-to-know
    * vagrant reload = vagrant halt + vagrant up https://www.vagrantup.com/docs/cli/reload.html
    * https://stackoverflow.com/questions/46903623/how-to-use-firefox-ui-in-vagrant-box
    * https://stackoverflow.com/questions/22651399/how-to-install-firefox-in-precise64-vagrant-box
      sudo apt-get -y install firefox
    * vagrant install emacs: https://medium.com/@AnnaJS15/getting-started-with-virtualbox-and-vagrant-8d98aa271d2a

    * hadoop conf: sudo vi /usr/local/hadoop-2.7.6/etc/hadoop/mapred-site.xml
    * https://data-flair.training/forums/topic/mkdir-cannot-create-directory-data-name-node-is-in-safe-mode/

-------------------------------------------------
B. Create IAM role on Amazon AWS to use S3 (S3a)
-------------------------------------------------
CommonCrawl (CC) crawl data is stored on Amazon S3, specifically the newest version Amazon s3a which has superceded both s3 and its earlier successor s3n.

In order to have access to cc crawl data, need to create an IAM role on Dr Bainbridge's Amazon AWS account and configure its profile for commoncrawl.

1. Log into Dr Bainbridge's Amazon AWS account
- In the aws management console:
[email protected]
lab pwd, capital R and ! (maybe g)


2. Create a new "iam" role or user for "commoncrawl(er)" profile

3. You can create the commoncrawl profile while creating the user/role, by following the instructions at https://answers.dataiku.com/1734/common-crawl-s3
which states

"Even though the bucket is public, if your AWS key does not have your full permissions (ie if it's a restricted IAM user), you need to grant explicit access to the commoncrawl bucket: attach the following policy to your IAM user"

#### START POLICY IN JSON FORMAT ###
{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Sid": "Stmt1503647467000",
            "Effect": "Allow",
            "Action": [
                "s3:GetObject",
                "s3:ListBucket"
            ],
            "Resource": [
                "arn:aws:s3:::commoncrawl/*",
                "arn:aws:s3:::commoncrawl"
            ]
        }
    ]
}
#### END POLICY ###


--------------------------------------------------------------------------
C. Configure Spark on your vagrant VM with the AWS authentication details
--------------------------------------------------------------------------
Any Spark jobs run against the CommonCrawl data stored on Amazon s3a need to be able to authenticate with the AWS IAM role you created above. In order to do this, you'll want to put the Amazon AWS access key and secret key in the SPARK configuration properties file. (Instead of configuring these values in hadoop's core-site.xml, as in the latter case, the authentication details don't get copied across when distributed jobs are run to other computers in the distributed cluster that also need to know how to authenticate):

1. Inside the vagrant vm:

   sudo emacs /usr/local/spark-2.3.0-bin-hadoop2.7/conf/spark-defaults.conf
   (sudo emacs $SPARK_HOME/conf/spark-defaults.conf)

2. Edit the spark properties conf file to contain these 3 new properties:

    spark.hadoop.fs.s3a.impl=org.apache.hadoop.fs.s3a.S3AFileSystem  
    spark.hadoop.fs.s3a.access.key=PASTE_IAM-ROLE_ACCESSKEY_HERE
    spark.hadoop.fs.s3a.secret.key=PASTE_IAM-ROLE_SECRETKEY_HERE

Instructions on which properties to set were taken from:
- https://stackoverflow.com/questions/30385981/how-to-access-s3a-files-from-apache-spark
- https://community.cloudera.com/t5/Community-Articles/HDP-2-4-0-and-Spark-1-6-0-connecting-to-AWS-S3-buckets/ta-p/245760

[NOTE, inactive alternative: Instead of editing spark's config file to set these properties, these properties can also be set in the bash script that executes the commoncrawl Spark jobs:

$SPARK_HOME/bin/spark-submit \
   ...
   --conf spark.hadoop.fs.s3a.access.key=ACCESSKEY \
   --conf spark.hadoop.fs.s3a.secret.key=SECRETKEY \
   --conf spark.hadoop.fs.s3a.impl=org.apache.hadoop.fs.s3a.S3AFileSystem \
   ...

But better not to hardcode authentication details into code, so I did it the first way.
]

----------------------------------------------------------------------
NOTE:
Script scripts/setup.sh now is automated to do the steps in D-F below
and prints out the main instruction for G.


----------------------------------------------------------------------
D. OPTIONAL? Further configuration for Hadoop to work with Amazon AWS
----------------------------------------------------------------------
The following 2 pages state that additional steps are necessary to get hadoop and spark to work with AWS S3a:

- https://stackoverflow.com/questions/30385981/how-to-access-s3a-files-from-apache-spark
- https://community.cloudera.com/t5/Community-Articles/HDP-2-4-0-and-Spark-1-6-0-connecting-to-AWS-S3-buckets/ta-p/245760

I'm not sure whether these steps were really necessary in my case, and if so, whether it was A or B below that got things working for me. However, I have both A and B below set up.


A. Check your maven installation for necessary jars:

1. Installing maven may already have got the specifically recommended version of AWS-Java-SDK (aws-java-sdk-1.7.4.jar) and v2.7.6 hadoop-aws matching the vagrant VM's hadoop version (hadoop-aws-2.7.6.jar). Check these locations, as that's where I have them:
- /home/vagrant/.m2/repository/com/amazonaws/aws-java-sdk/1.7.4/aws-java-sdk-1.7.4.jar
- /home/vagrant/.m2/repository/org/apache/hadoop/hadoop-aws/2.7.6/hadoop-aws-2.7.6.jar

The specifically recommended v.1.7.4 from the instructions can be found off https://mvnrepository.com/artifact/com.amazonaws/aws-java-sdk/1.7.4 at https://repo1.maven.org/maven2/com/amazonaws/aws-java-sdk/1.7.4/aws-java-sdk-1.7.4.jar

2. The script that runs the 2 Spark jobs uses the above paths for one of the spark jobs:
   $SPARK_HOME/bin/spark-submit \
       --jars file:/home/vagrant/.m2/repository/com/amazonaws/aws-java-sdk/1.7.4/aws-java-sdk-1.7.4.jar,file:/home/vagrant/.m2/repository/org/apache/hadoop/hadoop-aws/2.7.6/hadoop-aws-2.7.6.jar \
       --driver-class-path=/home/vagrant/.m2/repository/com/amazonaws/aws-java-sdk/1.7.4/aws-java-sdk-1.7.4.jar:/home/vagrant/.m2/repository/org/apache/hadoop/hadoop-aws/2.7.6/hadoop-aws-2.7.6.jar \

However the other Spark job in the script does not set --jars or --driver-class-path, despite also referring to the s3a://commoncrawl table. So I'm not sure whether the jars are necessary or whether theywere just being ignored when provided.

B. Download jar files and put them on the hadoop classpath:

1. download the jar files:
- I obtained aws-java-sdk-1.11.616.jar (v1.11) from https://aws.amazon.com/sdk-for-java/

- I downloaded hadoop-aws 2.7.6 jar, as it goes with my version of hadoop, from https://mvnrepository.com/artifact/org.apache.hadoop/hadoop-aws/2.7.6

2. The easiest solution is to copy the 2 downloaded jars onto a location in the hadoop classpath.

a. The command that shows the paths present on the Hadoop CLASSPATH:
    hadoop classpath
One of the paths this will list is /usr/local/hadoop-2.7.6/share/hadoop/common/

b. SUDO COPY the 2 downloaded jar files, hadoop-aws-2.7.6.jar and aws-java-sdk-1.11.616.jar, to this location:

     sudo cp hadoop-aws-2.7.6.jar /usr/local/hadoop-2.7.6/share/hadoop/common/.
     sudo cp aws-java-sdk-1.11.616.jar /usr/local/hadoop-2.7.6/share/hadoop/common/.

Any hadoop jobs run will now find these 2 jar files on the classpath.

[NOTE, unused alternative: Instead of copying the 2 jar files into a system location, assuming they were downloaded into /home/vagrant/lib, you can also export a custom folder's jar files into the hadoop classpath from the bash script that runs the spark jobs. This had no effect for me, and was commented out, and is another reason why I'm not sure if the 2 jar files were even necessary.
#export LIBJARS=/home/vagrant/lib/*                                 
#export HADOOP_CLASSPATH=`echo ${LIBJARS} | sed s/,/:/g`
]


------------------------------------
E. Setup cc-index-table git project
------------------------------------
Need to be inside the vagrant VM.

1. Since you should have already installed maven, you can checkout and compile the cc-index-table git project.

       git clone https://github.com/commoncrawl/cc-index-table.git

2. Modify the toplevel pom.xml file used by maven by changing the spark version used to 2.3.0 and adding a dependency for hadoop-aws 2.7.6, as indicated below:

17c17,18
<       <spark.version>2.4.1</spark.version>
---
>       <!--<spark.version>2.4.1</spark.version>-->
>       <spark.version>2.3.0</spark.version>
135a137,143
>       <dependency>
>         <groupId>org.apache.hadoop</groupId>
>         <artifactId>hadoop-aws</artifactId>
>         <version>2.7.6</version>
>       </dependency>
> 

3. Although cc-index-table will compile successfully after the above modifications, it will nevertheless throw an exception when it's eventually run. To fix that, edit the file "cc-index-table/src/main/java/org/commoncrawl/spark/examples/CCIndexWarcExport.java" as follows:

a. Set option(header) to false, since the csv file contains no header row, only data rows.
   Change:
    sqlDF = sparkSession.read().format("csv").option("header", true).option("inferSchema", true)
                                        .load(csvQueryResult);
   To
    sqlDF = sparkSession.read().format("csv").option("header", false).option("inferSchema", true)
                                        .load(csvQueryResult);

b. The 4 column names are inferred as _c0 to _c3, not as url/warc_filename etc.
   Comment out:
    //JavaRDD<Row> rdd = sqlDF.select("url", "warc_filename", "warc_record_offset", "warc_record_length").rdd()
                                .toJavaRDD();
   Replace with the default inferred column names:
    JavaRDD<Row> rdd = sqlDF.select("_c0", "_c1", "_c2", "_c3").rdd()
                                .toJavaRDD();

// TODO: link svn committed versions of orig and modified CCIndexWarcExport.java here.

4. Now (re)compile cc-index-table with the above modifications:

   cd cc-index-table
   mvn package

-------------------------------
F. Setup warc-to-wet tools
-------------------------------
To convert WARC files to WET (.warc.wet) files, need to checkout, set up and compile a couple more tools. These instructions are derived from those at https://groups.google.com/forum/#!topic/common-crawl/hsb90GHq6to

1. Grab and compile the 2 git projects for converting warc to wet:
     git clone https://github.com/commoncrawl/ia-web-commons
     cd ia-web-commons
     mvn install

     git clone https://github.com/commoncrawl/ia-hadoop-tools
     cd ia-hadoop-tools
     # can't compile this yet
     

2. Add the following into ia-hadoop-tools/pom.xml, in the top of the <dependencies> element, so that maven finds an appropriate version of the org.json package and its JSONTokener (version number found off https://mvnrepository.com/artifact/org.json/json):

   <dependency>
      <groupId>org.json</groupId>
      <artifactId>json</artifactId>
      <version>20131018</version>
    </dependency>

[
  UNFAMILAR CHANGES that I don't recollect making and that may have been a consequence of the change in step 1 above:
  a. These further differences show up between the original version of the file in pom.xml.orig and the modified new pom.xml:
  ia-hadoop-tools>diff pom.xml.orig pom.xml

  <       <groupId>org.netpreserve.commons</groupId>
  <       <artifactId>webarchive-commons</artifactId>
  <       <version>1.1.1-SNAPSHOT</version>
  ---
  >       <groupId>org.commoncrawl</groupId>
  >       <artifactId>ia-web-commons</artifactId>
  >       <version>1.1.9-SNAPSHOT</version>

  b. I don't recollect changing or manually introducing any java files. I just followed the instructions at https://groups.google.com/forum/#!topic/common-crawl/hsb90GHq6to

  However, a diff -rq between the latest "ia-hadoop-tools" gitproject checked out a month after the "ia-hadoop-tools.orig" checkout I ran, shows the following differences in files which are not shown as recently modified in github itself in that same period.

  ia-hadoop-tools> diff -rq ia-hadoop-tools ia-hadoop-tools.orig/
  Files ia-hadoop-tools/src/main/java/org/archive/hadoop/io/HDFSTouch.java and ia-hadoop-tools.orig/src/main/java/org/archive/hadoop/io/HDFSTouch.java differ
  Only in ia-hadoop-tools/src/main/java/org/archive/hadoop/jobs: ArchiveFileExtractor.java
  Files ia-hadoop-tools/src/main/java/org/archive/hadoop/jobs/CDXGenerator.java and ia-hadoop-tools.orig/src/main/java/org/archive/hadoop/jobs/CDXGenerator.java differ
  Files ia-hadoop-tools/src/main/java/org/archive/hadoop/jobs/JobDriver.java and ia-hadoop-tools.orig/src/main/java/org/archive/hadoop/jobs/JobDriver.java differ
  Files ia-hadoop-tools/src/main/java/org/archive/hadoop/jobs/WARCMetadataRecordGenerator.java and ia-hadoop-tools.orig/src/main/java/org/archive/hadoop/jobs/WARCMetadataRecordGenerator.java differ
  Files ia-hadoop-tools/src/main/java/org/archive/hadoop/jobs/WATGenerator.java and ia-hadoop-tools.orig/src/main/java/org/archive/hadoop/jobs/WATGenerator.java differ
  Only in ia-hadoop-tools.orig/src/main/java/org/archive/hadoop/jobs: WEATGenerator.java
  Files ia-hadoop-tools/src/main/java/org/archive/hadoop/mapreduce/ZipNumPartitioner.java and ia-hadoop-tools.orig/src/main/java/org/archive/hadoop/mapreduce/ZipNumPartitioner.java differ
  Files ia-hadoop-tools/src/main/java/org/archive/hadoop/pig/ZipNumRecordReader.java and ia-hadoop-tools.orig/src/main/java/org/archive/hadoop/pig/ZipNumRecordReader.java differ
  Files ia-hadoop-tools/src/main/java/org/archive/hadoop/streaming/ZipNumRecordReader.java and ia-hadoop-tools.orig/src/main/java/org/archive/hadoop/streaming/ZipNumRecordReader.java differ
  Files ia-hadoop-tools/src/main/java/org/archive/server/FileBackedInputStream.java and ia-hadoop-tools.orig/src/main/java/org/archive/server/FileBackedInputStream.java differ
  Files ia-hadoop-tools/src/main/java/org/archive/server/GZRangeClient.java and ia-hadoop-tools.orig/src/main/java/org/archive/server/GZRangeClient.java differ
  Files ia-hadoop-tools/src/main/java/org/archive/server/GZRangeServer.java and ia-hadoop-tools.orig/src/main/java/org/archive/server/GZRangeServer.java differ
]

3. Now can compile ia-hadoop-tools:
   cd ia-hadoop-tools
   mvn package

4. Can't run it until guava.jar is on hadoop classpath. Locate a guava.jar and put it into an existing location checked for by hadoop classpath:

   locate guava.jar
       # found in /usr/share/java/guava.jar and /usr/share/maven/lib/guava.jar
   diff /usr/share/java/guava.jar /usr/share/maven/lib/guava.jar   
    # identical/no difference, so can use either
   sudo cp /usr/share/java/guava.jar /usr/local/hadoop/share/hadoop/common/.
    # now guava.jar has been copied into a location on hadoop classpath


Having done the above, our bash script will now be able to convert WARC to WET files when it runs:
    $HADOOP_MAPRED_HOME/bin/hadoop jar $PWD/target/ia-hadoop-tools-jar-with-dependencies.jar WEATGenerator -strictMode -skipExisting batch-id-xyz hdfs:///user/vagrant/PATH/TO/warc/*.warc.gz
Our script expects a specific folder structure: there should be a "warc" folder (containing the warc files), which is supplied as above, but also an empty "wet" and "wat" folder at the same level as the "warc" folder.


When the job is running, can visit the Spark Context at http://node1:4040/jobs/ (http://node1:4041/jobs/ for me first time, since I forwarded the vagrant VM's ports at +1. However, subsequent times it was on node1:4040/jobs?)

-----------------------------------
G. Getting and running our scripts
-----------------------------------

1. Grab our 1st bash script and put it into the /home/vagrant/cc-index-table/src/script:
       cd cc-index-table/src/script
       wget http://svn.greenstone.org/gs3-extensions/maori-lang-detection/hdfs-cc-work/scripts/get_maori_WET_records_for_crawl.sh
       chmod u+x get_maori_WET_records_for_crawl.sh

RUN AS:
cd cc-index-table
./src/script/get_maori_WET_records_for_crawl.sh <crawl-timestamp>
                where crawl-timestamp of form "CC-MAIN-YYYY-##" >= September 2019

OUTPUT:
After hours of processing (leave it to run overnight), you should end up with:
      hdfs dfs -ls /user/vagrant/<crawl-timestamp>
In particular, the zipped wet records at hdfs:///user/vagrant/<crawl-timestamp>/wet/
that we want would have been copied into /vagrant/<crawl-timestamp>-wet-files/


The script get_maori_WET_records_for_crawl.sh
- takes a crawl timestamp of the form "CC-MAIN-YYYY-##" from Sep 2018 onwards (before which content_languages were not indexed). The legitimate crawl timestampts are listed in the first column at http://index.commoncrawl.org/
- runs a spark job against CC's AWS bucket over s3a to create a csv table of MRI language records
- runs a spark job to download all the WARC records from CC's AWS that are denoted by the csv file's records into zipped warc files
- converts WARC to WET: locally converts the downloaded warc.gz files into warc.wet.gz (and warc.wat.gz) files


2. Grab our 2nd bash script and put it into the top level of cc-index-table (/home/vagrant/cc-index/table):

       cd cc-index-table
       wget http://svn.greenstone.org/gs3-extensions/maori-lang-detection/hdfs-cc-work/scripts/get_Maori_WET_records_from_CCSep2018_on.sh
       chmod u+x get_Maori_WET_records_from_CCSep2018_on.sh

RUN FROM cc-index-table DIRECTORY AS:
    (cd cc-index-table)
    ./get_Maori_WET_records_from_CCSep2018_on.sh

This script just runs the 1st script cc-index-table/src/script/get_maori_WET_records_for_crawl.sh (above) to process all listed common-crawls since September 2018.
If any fails, then the script will terminate. Else it runs against each common-crawl in sequence.

NOTE: If needed, update the script with more recent crawl timestamps from http://index.commoncrawl.org/

OUTPUT:
After days of running, will end up with:
      hdfs:///user/vagrant/<crawl-timestamp>/wet/
for each crawl-timestamp listed in the script,
which at present would have got copied into
      /vagrant/<crawl-timestamp>-wet-files/

Each of these output wet folders can then be processed in turn by CCWETProcessor.java from http://trac.greenstone.org/browser/gs3-extensions/maori-lang-detection/src/org/greenstone/atea/CCWETProcessor.java


-----------------------EOF------------------------