If you are familiar with Docker you can follow these instructions to get going as quickly as possible.
These instructions reflect the use of Docker for Windows or Docker for Mac, both of which provide tight integration of Docker with the operating system. The instructions should be the same for Docker on Linux.
The D4ST system uses git to manage your source code. You must have a git client installed on your machine. Under macOS this should already be the case (test it by typing "git" in a command window). The built-in version of git may be older than you want, in which case you can use homebrew to install a newer version of git (see https://brew.sh).
For Windows you can install Git For Windows, which is a free git client. Be sure to include the git bash shell in your installation.
For both macOS and Windows the free SourceTree application from Atlassian provides a complete git user interface. For Windows, the free Tortoise Git provides integration of git with Windows Explorer.
Under Windows, open a Docker Quickstart Terminal window () or a Git for Windows shell (both provide a Linux-style command environment).
Under macOS you can use a normal terminal window.
Download the DITA for Small Teams d4st-docker Zip package from the dita-for-small-teams project releases area:
Unzip the D4ST release package to somewhere convenient, e.g. c:\apps or ~/apps. This is where the d4st command will live.
You should get a directory named d4st-docker with this content:
LICENSE
README.md
containers
d4st
The d4st script is the main script for managing the D4ST components through Docker. It is a bash shell script intended to be run in a bash shell. Under Windows you can run it in a git bash shell.
Start a bash shell (under Windows, a git command window, which provides a bash shell) and navigate to the directory for the D4ST package:
ekimber@WIN-HH0I81E3DAU MINGW64 /c
$ cd apps/d4st-docker
ekimber@WIN-HH0I81E3DAU MINGW64 /c/apps/d4st-docker
$ ls
bin/ containers/ d4st docs/ LICENSE README.md
Run the command "chmod a+x d4st" to make the d4st script executable.
You can check this by doing "ls -al d4st" to see what the permissions are. You should see "x"s in the permissions:
$ ls -al d4st
-rwxr-xr-x 1 ekimber staff 13437 Mar 19 15:39 d4st
$
Unfortunately, there doesn't appear to be a way to preserve the executable flag in the Zip file. If anyone knows a way to get around this that doesn't require an actual installer, please speak up.
Run the command "./d4st start":
ekimber@WIN-HH0I81E3DAU MINGW64 /c/temp/d4st-docker
$ ./d4st start
Starting D4ST Docker containers in the background. Use docker-compose commands or Kitematic to view the status.
Pulling redis (sameersbn/redis:latest)...
latest: Pulling from sameersbn/redis
… lots more messages here ...
Creating gitlab-d4st
Docker containers:
CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES
7971effdd6cb d4st/gitlab-d4st "/assets/wrapper" 3 seconds ago Up Less than a second 0.0.0.0:80->80/tcp, 0.0.0.0:443->443/tcp, 0.0.0.0:8022->22/tcp gitlab-d4st
9693d356371d d4st/caddy-d4st "/usr/bin/caddy --..." 13 seconds ago Up 10 seconds 80/tcp, 443/tcp, 0.0.0.0:80->2015/tcp caddy-d4st
aab650590a70 d4st/link-manager-basex "/opt/basex/bin/basex" 2 minutes ago Up 2 minutes 0.0.0.0:1984->1984/tcp, 0.0.0.0:8984->8984/tcp linkmgr-d4st
a280cacb6079 sameersbn/postgresql:9.4-12 "/sbin/entrypoint.sh" 2 minutes ago Up 2 minutes 5432/tcp d4stdocker_postgresql_1
f15cb9d8c17a sameersbn/redis:latest "/sbin/entrypoint.sh" 4 minutes ago Up 4 minutes 6379/tcp
d4stdocker_redis_1
The first time you do this Docker has to download all the images for the containers and this can take a while. The next time you run it, it will be quick.
The exact set of containers may be different depending on the current configuration of the D4ST container set.
The D4ST containers should start. It will take a minute or two for the Web services in the containers to start up completely.
The first time you run the d4st command it creates the file d4st/.env. This file contains environment settings used by the docker commands. You can edit this file to change the ports used by the different D4ST Web services. You will also edit this file to add the GitLab private token in a later step.
The first time you run GitLab it has to do quite a lot of setup and that may take several minutes to complete. You can use the command d4st log-gitlab to see what it's doing and monitor it's startup progress.
If you get messages about containers not starting because their ports are taken, for example because you already have something running on port 80 or port 8080 (default ports for many applications), you can edit the .env file that the d4st command created the first time you ran it. See step 11.
To make things easier later, add the d4st directory to the PATH environment variable in your command window:
$ export PATH=$PATH:$PWD
The $PWD environment variable expands to the current directory, so the d4st directory should now be in your PATH environment variable.
To make this setting permanent you can modify your .bash_profile (OSX) or .bashrc (Windows, Linux) file in your home directory to add the d4st directory to the PATH, e.g.:
You should be able to run the d4st command from any directory. You can test this by using the cd command to move to another directory and then execute the command d4st help. You should get the listing of available d4st commands.
If the d4st command doesn't work, check the value of the $PATH environment variable using the echo command:
Check the value and make sure it's correct. If it's not correct, try setting it again.
To use GitLab as a remote git repository you must set up a GitLab user for yourself (or anyone who will be connecting to the GitLab server) and then create GitLab projects corresponding to your local git repositories that you want to use with the D4ST system. This requires a one-time task of logging into GitLab as the root user so you can get the magic "private token" required to use the GitLab API. Once you've done this the rest of the user and project setup can be done with the d4st command.
In the Docker terminal, type the command "d4st gitlab" to open the GitLab Web application.
Your browser should open to the GitLab login page:
Figure 1. GitLab Login Screen
If your browser doesn't open, make sure you have Google Chrome installed.
The first time you connect to GitLab you will be asked to set the password for the user "root".
Choose any password you like as long as you can remember it. You should then be taken to the normal login screen. Log in as user "root" with the password you just set.
The password will be reasonably secure as stored in the GitLab container so it should be safe to use your regular password.
You should be logged into GitLab as user "root".
Select "Settings" in the drop-down menu under your user avatar in the upper-right corner (the avatar will be a generated pattern). From the list of options along the top of the User Settings page, select "Account" to get to the account details for user "root".
You should see a field labeled "Private token" at the top of the page containing a value like "zdPgyhv6rnZfDsqHxqKZ".
Copy the private token string to the clipboard.
Edit the docker-d4st/.env file and replace "YourPrivateToken" with the value on the clipboard:
Verify that you have set the private token correctly by using the command d4st test-gitlab.
$ ./d4st test-gitlab
Testing GitLab connection...
Success: Connected to GitLab remote API using private token.
$
Create a GitLab user for yourself by using the command d4st make-gitlab-user:
$ d4st make-gitlab-user
$
The password is set to "password" for the new user. You can change it using the GitLab administration pages. This password will be needed when you connect your local git repository to gitlab.
If you want to set the password when you create the user you can specify the username and password on the d4stmake-gitlab-user command:
$ d4st make-gitlab-user ekimber swordfish
$
However, this isn't very secure. If you're concerned about the security of the GitLab credentials, use the GitLab Web interface to change the password.
At this point you should be ready to create new projects in GitLab and connect them to your local git repositories on your machine. You can use any git repository you have but for demo purposes the DITA Community DITA Demo content collection (the "Thunderbird" document set) has been included to make it easy to get started. To use it you just need to copy it out of its container to your local machine.
In the Docker terminal execute the command d4st getdemo, specifying the directory you want to put the Thunderbird directory into:
$ ./d4st getdemo ~
This copies the Thunderbird directory from the container to Thunderbird under your home directory. You can replace "~" with whatever target directory you want.
Test the copy:
$ ls ~/Thunderbird
Integrator_admin.ditamap
ditavals
master_control_jp.ditamap
Integrator_admin_jp.ditamap
en
proposal_template.ditamap
User_Guide-reuse-only.ditamap
jp
proposal_template_jp.ditamap
User_Guide-reuse-only_jp.ditamap master_control.ditamap
You now have a copy of the Thunderbird data ready to push to your GitLab server once you have created a corresponding GitLab project for the Thunderbird git repository.
In the command window, navigate into the Thunderbird directory and execute the command d4st make-gitlab-project:
$ cd ~/Thunderbird
$ d4st make-gitlab-project
Creating GitLab project "Thunderbird" for user ekimber...
Success: Project "Thunderbird" created.
*** remote="origin"
$
A GitLab project for the current user and with the same name as the current directory has been created. The command also automatically sets the new GitLab repository as the remote repository named "origin". If the directory you're creating the project for already has an associated remote named "origin" it will use the name "gitlab" for the GitLab remote.
Verify this by using the git remote -v command to see that the remote repository has been hooked up:
You can also use the GitLab Web interface to verify that the project has been created.
Push the contents of the Thunderbird repository to the GitLab project using the command git push -u origin master. The git command will ask you for your gitlab user ID and password if you haven't done this before. (Git has different options for storing credentials so after you've done this once it should remember your user ID and password.)
$ git push -u origin master
Counting objects: 132, done.
Delta compression using up to 8 threads.
Compressing objects: 100% (130/130), done.
Writing objects: 100% (132/132), 675.62 KiB | 0 bytes/s, done.
Total 132 (delta 13), reused 0 (delta 0)
remote: Running post-receive...
remote: getRepoName(): parts=["", "var", "opt", "gitlab", "git-data", "repositories", "ekimber", "thunderbird.git"]
remote: [1] repoName=thunderbird2.git
remote: [2] repoName=thunderbird2
remote: Updating using 4b825dc642cb6eb9a060e54bf8d69288fbee4904, 956a167f798801b837702c6655d2401516f02f24, refs/heads/master
remote: Added or modified file: "Integrator_admin.ditamap"
remote: Adding file "Integrator_admin.ditamap" to database d4st^thunderbird^master...
remote: Resource(s) added in 530.15 ms.
… {lots more messages} …
remote: *** Updating fulltext index for database d4st^thunderbird^master
remote: Post-receive done.
To http://localhost:90/ekimber/Thunderbird.git
* [new branch] master -> master
$
The command will take a little while to complete because it's copying all the XML files to the Link Manager database.
The Thunderbird files have been pushed to the remote GitLab repository and copied to the D4ST Link Manager database. You can use the GitLab Web application to verify that the files are now in GitLab.
In the bash terminal enter the command "d4st linkmgr" to open the Link Manager Web application in a new browser window.
The URL for the Link Manager Web application is http://localhost:8984.
The Link Manager application should open. You should see an entry like "Thunderbird/master" in the list of repositories and branches. You can click on the branch to see the files in the branch.
Click on the link to the master branch to access the link manager application for that branch.
Observe that the "Root Map" column under DITA Maps shows "?" (question marks). The "Root Map" column indicates whether or not a give map a root map, as determined by whether or not the map is referenced as a submap by any other maps. The question marks indicate that the link management indexes have not yet been updated for the project.
Click on the "Update Link Management Indexes" link near the top of the page.
A new tab will open with the text "Updating link management indexes". After some time (should not be more than a minute on a reasonably-fast machine) the message will be replaced with the text "Link management database updated".
Close the tab with the "Link management database updated" message and return to the page for the Thunderbird/master branch. Refresh the page.
The Root Map column should now show check marks for four of the maps and nothing for two other maps. This indicates that the link management indexes have been updated.
At this point you can explore the Link Manager application.
You now have a sample DITA-based documentation source repository, the Thunderbird project, set up and connected to the D4ST link manager. You can experiment with modifying the source files and committing new versions to GitLab or creating new branches and seeing how those updates and new branches are reflected in the D4ST Link Manager.
The D4ST Docker setup includes a local oXygenXML Web Author server that integrates with GitLab. The D4ST Link Manager includes "edit" links from each file to oXygenXML Web Author, providing built-in editing support out of the box. Note that the license for oXygenXML Web Author is a demo license and should not be used for production work. Context Syncro Soft to acquire a Web Author license.
To test editing with oXygenXML Web Author go to the D4ST Link Manager, navigate to page for a repository and branch (you should already be there if you haven't done anything after the previous step), and click the "edit" link next to any file.
The oXygenXML Web Author page will open and attempt to open the file you selected from the GitLab repository.
The first time you do this you will need to create an oXygenXML Web Author administrative user, e.g. "admin" with a password of "admin". Because this server is running locally there's no need for greater security.
Once you create the admin user it will attempt to open an editor for the file you selected. The first time you do this you'll need to provide your GitLab user name and password (your personal one, not the GitLib root user).
Make a change to the title of the map or topic and click on the git icon () to commit your changes to GitLab.
Your changes should be committed to GitLab.
If you refresh the Link Manager view for the branch you just committed to it should reflect the change you committed. You can also preview the file to verify that the changes are there.
Having followed this process you should be able to quickly add your own documents' git repositories to the D4ST GitLab server in order to take advantage of the D4ST Link Manager.
) or a Git for Windows shell (both provide a Linux-style command environment).
) to commit your changes to GitLab.