metanorma / metanorma-windows-setup

Metanorma setup instructions for Windows

Metanorma Windows Setup

Note	Installation instructions in this repository are no longer maintained or recommended. Please refer to Metanorma installation docs (which also cover Windows) instead.

Purpose

This repository provides installation of the Metanorma publication toolchain on Windows.

There are two types of installation:

• Docker: allows easier management of dependencies

• Native: better performance

Requirements

• Windows 8+ for native installation

• Windows 10 for the “Docker for Windows” installation

Older versions may work but are not tested.

Quick install

Open PowerShell with Administrator rights

Right-click on the “Start” menu, and click on “Windows PowerShell (Admin)”.

You will be presented with the following alert, click “Yes” to start the shell.

Native installation

Run the commands as specified:

If you’d like to run via cmd.exe (run with Administrator privileges):

bitsadmin /transfer get https://raw.githubusercontent.com/metanorma/metanorma-windows-setup/master/install.bat %cd%\install.bat & .\install.bat

If you’d like to run via PowerShell (again, run with Administrator privileges):

(Invoke-WebRequest 'https://raw.githubusercontent.com/metanorma/metanorma-windows-setup/master/install.bat' -OutFile 'install.bat'); .\install.bat

Docker installation

Run the commands as specified:

If you’d like to run via cmd.exe (run with Administrator privileges):

bitsadmin /transfer get https://raw.githubusercontent.com/metanorma/metanorma-windows-setup/master/docker.bat %cd%\docker.bat & .\docker.bat

If you’d like to run via PowerShell (again, run with Administrator privileges):

(Invoke-WebRequest 'https://raw.githubusercontent.com/metanorma/metanorma-windows-setup/master/docker.bat' -OutFile 'docker.bat'); .\docker.bat

Manual Install

If automatic installation doesn’t work for you for some reason, follow steps bellow.

Docker install

General

Running Metanorma requires installation of the following software:

• “Docker” is required to run Metanorma on Windows;

• “Git” is recommended for sharing and running the examples;

There are two ways to install prerequisite packages on Windows:

• Via the Chocolatey package manager (recommended). Chocolatey allows you to mostly automate the install process without human input.

• Via manual downloads and installs

Install “Chocolatey”

You can install Chocolatey with cmd.exe or PowerShell.

Let’s take the PowerShell method as an example.

Note	Refer to detailed steps here: https://chocolatey.org/install

Run Chocolatey install script in PowerShell

Inside the PowerShell with Administrator rights, paste the following commands into it.

Set-ExecutionPolicy Bypass -Scope Process -Force; iex ((New-Object System.Net.WebClient).DownloadString('https://chocolatey.org/install.ps1'))

Install “Git”

We strongly recommend installing “Git” using Chocolatey.

Install Git using Chocolatey

All you need is to run the following command:

choco install git -y

Install Git manually

Go to this website to download “Git for Windows”:

https://git-scm.com/download/win

And install it.

Install “Docker for Windows”

Again, life is much easier using Chocolatey.

Install Docker for Windows using Chocolatey

The following command installs “Docker for Windows”

choco install docker-for-windows -y

Install Docker for Windows manually

1. Go to the Docker Store to download “Docker for Windows”

   1. While the Docker Store asks you to login before downloading, the link is actually available without needing to authenticate (download link)

      

   2. Open the downloaded file.

      

2. Allow the install to execute with administrative access

   

3. See the installation progress.

   

4. Continue with the default configuration. DO NOT select “Use Windows containers instead of Linux containers” otherwise the Metanorma container cannot run. It must be run with “Linux containers”.

   

   1. (Luckily, if you have selected this, it is switchable afterwards)

5. Installation is completed and a restart is required.

   

Post-install

This section is relevant regardless of which method you used to install Docker for Windows.

On the first restart, you will asked by Docker to enable Hyper-V and the Containers service as shown below. This is mandatory for running Docker on Windows. Click “OK” to accept the install and restart, but remember to switch back to using “Linux containers” prior to running Metanorma.

After the restart you will see Docker being up as shown below!

Switching Docker to use Linux containers

If you mistakenly enabled “Windows containers”, you will have to switch back to “Linux containers” to run the Metanorma container.

Otherwise you will be given the dreaded “image operating system “linux” cannot be used on this platform”.

1. Right click on the docker taskbar icon, and click “Switch to Linux containers”

2. See the following prompt, click “Switch”

   

3. Wait until the docker taskbar icon indicates that docker is up again.

Verify everything works

Special notes for Docker installation

Drive sharing with Docker

When running the following commands, you may be prompted to share your current drive, such as “C:\”, as shown below. This is necessary to allow the Metanorma Docker container to read the files in the cloned directory.

Click “Share It” to share the drive with the Metanorma Docker container.

Running Docker on Windows within a VM

If you are running Windows via virtualization, you must set your hypervisor to enable hardware virtualization for the Windows VM.

For example, this screenshot shows you how to enable VT-x in a VM on VMWare Fusion:

Example: ISO Rice document

Clone source

git clone https://github.com/metanorma/isodoc-rice
cd isodoc-rice

Run on native installation

make -f Makefile.win clean all

Run on Docker installation

docker run -v ${pwd}:/metanorma/ ribose/metanorma "metanorma -t iso -x html,xml,doc iso-rice-en.adoc"

Verify generated files

Then you can open the generated HTML file in PowerShell using Internet Explorer Edge:

Invoke-Item iso-rice-en.html

Example: UNECE Recommendation 42

Clone source

git clone https://github.com/metanorma/unece-cefact-recommendation-42
cd unece-cefact-recommendation-42

Run on native installation

make -f Makefile.win clean all

Run on Docker installation

docker run -v ${pwd}:/metanorma/ ribose/metanorma "metanorma -t cefact -x html,xml,doc unece-cefact-recommendation-42.adoc"

Verify generated files

Then you can open the generated HTML file in PowerShell using Internet Explorer Edge:

Invoke-Item unece-cefact-recommendation-42.html

Debugging

If you run into any problems, please copy and paste the entire log into a new GitHub Issue for us.

metanorma-windows-setup's Issues

Create Chocolatey package for Metanorma

Is this repository deprecated?

Is this repository deprecated in favour of https://github.com/metanorma/chocolatey-metanorma?

If it is, the README needs to clearly state that this is no longer active code, and point to chocolatey-metanorma.

Add AppVeyor badge

https://ci.appveyor.com/api/projects/status/vqo2221uwcaov8kx?svg=true

Develop Metanorma Windows setup instructions

Like the macOS version.

https://github.com/riboseinc/metanorma-macos-setup/

• Package manager: use chocolatey
  • supports PlantUML, Ruby 2.5, Java, nodejs
  • puppeteer can be installed via npm (https://github.com/GoogleChrome/puppeteer)
  • sublime (https://chocolatey.org/packages?q=sublime)

Installing Chocolatey:

• https://medium.com/@JockDaRock/installing-the-chocolatey-package-manager-for-windows-3b1bdd0dbb49

Split Docker and Native Ruby installation scripts

Migrate this repository to github.com/metanorma

The repository github.com/metanorma has been set up to host all Metanorma related work. This is one such piece of work. While the migration will be slow (there is a lot to do, and a lot of interdependencies), we need to schedule migration for all related repositories.

Migration to Metanorma:

• Repost the repository to http://github.com/metanorma/X
  • This should be as simple as changing the following field in .git/config: [remote "origin"] url = https://github.com/riboseinc/metanorma-iso.git. Refer https://help.github.com/en/articles/transferring-a-repository
• If this is a Ruby gem, change the address of the repository in the *.gemspec
• Delete all files but the Readme in the riboseinc repository
• Replace the Readme in the riboseinc repository with the message "Repository migrated to http://github.com/metanorma/X
• Update the links to the repository in any documentation you maintain
• Link the README in the new location to updated links for appveyor, CodeClimate, travis, etc. New links to travis should be to travis-ci.com, not travis-ci.org.
• Notify @opoudjis and @strogonoff when you have migrated the repository. They will then update the links to the repository in any documentation they maintain.

Unable to install `metanorma-cli` gem in Windows following script

This command is supposed to install the gem, but nothing actually happens!

CALL %RUBY_BIN%\gem install metanorma-cli -- ^
	--with-xml2-include=%XSLT_INCLUDE%\libxml2 ^
	--with-xslt-include=%XSLT_INCLUDE% ^
	--with-xml2-lib=%XSLT_LIB_DIR% ^
	--with-xslt-lib=%XSLT_LIB_DIR% >> %INSTALL_LOG_FILE% 2>&1

@CAMOBAP795 can you please help fix this?

Migrate to GitHub Actions

And remove AppVeyor.

Make AppVeyor check UNECE Recommendation 42 document build

For @CAMOBAP795 .

From #3

This ticket is to add to the AppVeyor build script to build the UNECE Recommendation 42 document (https://github.com/riboseinc/unece-cefact-recommendation-42/pull/1/files#diff-180360612c6b8c4ed830919bbb4dd459) into this repo, so that we can test directly whether the windows setup script allows building the document immediately.

Thanks!