title: J1
Starter tagline: Create your Windows environment in 15 minutes description: Create your Windows environment in 15 minutes
tags: [ Starter, Windows, Template ] index: [] categories: [ pages ]
permalink: /pages/public/start/downloads/windows_starter/ regenerate: false
resources: [ lightbox, carousel ] resource_options:
- masthead: slides: # Broadway Underground - still image - url: /assets/videos/headers/still/underground-broadway.png alt: Broadway Underground alignY: top animateFirst: false # Broadway Underground - FAYETTE ST, moved file to Github/LFS - url: https://github.com/jekyll-one/jekyll-one-lfs/raw/master/videos/underground-broadway.mp4 alignY: 0 isVideo: true loop: true duration: 12000 # Broadway Underground - still image - url: /assets/videos/headers/still/underground-broadway.png alt: Broadway Underground alignY: top transitionDuration: 750 transition: "push_left|push_right|cover_up|cover_down|fade|fadeInOut"
// NOTE: General Asciidoc page attributes settings // :page-liquid:
{% comment %} Liquid procedures ————————————————————— {% endcomment %} {% capture set_env_entry_document %}themes/{{site.template.name}}/procedures/global/set_env_entry_document.proc{%endcapture%}
// NOTE: Initialize entry document paths // {% include {{set_env_entry_document}} init_folders=all %}
// Load tags and urls // include::{includedir}/attributes.asciidoc include::{includedir}/attributes.asciidoc
// Additional Asciidoc page attributes goes here //
Step in the fastest way¶ ↑
Creating a fully equipped Jekyll
developing enviroment may take a while
-
especially if you are on Windows or MacOS. If you work on Linux,
most of the needed tools are already installed or quite easy to install. That's because Linux support developer at it's best.
On Linux, all languages and tools are fully supported, mostly installed already or can be installed in minutes from prepared packages in their latest versions. Unfortuneatly, this is not the case on Windows. MacOS users will find some of the developing tools installed but mostly in unusable, quite old versions.
Bad luck? Not at all. Go for J1
Quickstart. Read for your platform the details.
Windows platform¶ ↑
The J1
team prepared a full development suite for Jekyll
on Windows that can be setup in 15 minutes. All packages needed are bundled together and can be installed by an Windows installer as usual.
If you're using Jekyll
on Windows already, the Quickstart package might be helpful as well. If you don't want to mixup already installed applications or install additional Rubies in your existing environment, you can go for the Quickstart package. All tools and their environments are localized to the application folder of J1
Quickstart and should not interfere with any of the already installed programs and their ressources.
MacOS platform¶ ↑
The availability of Open Source tools and applications are not the strenght of Apple products. Maybe because they can be used for free?
Yes, Perl, Ruby, Python etc. are available out of the box but they are pre-installed in unusable old versions. Upgrading these packages - no choice. You can go for HomeBrew to brew what you need - what many people does. The same to us - if we're on MacOS.
But as always: installing an bunch of software will take a while. No fun.
Installing the Quickstarter in done in a couple of minutes by unpacking an archive followed by an initialization step for the first start. That's it. No digging for the right versions.
If you're using Jekyll
on Mac already, the Quickstart package might be a good choice if you don't want to mixup already installed applications or install e.g. additional Rubies in your existing environment. You can go for the Quickstart package.
All tools and their environments are localized to the application path of J1
Quickstart and should not interfere with already installed programs and their ressources. By setting some environment variables, all the systems you've prepared for your projects will be left untouched. And you're done in about 15 minutes.
Sounds good?
Linux platform¶ ↑
Linux is the preferred platform for Open Source developers. No wonder, all ressources you need for a Jekyll
developing system are well prepared or already available with the distribution you're using.
But …
If you don't want to mixup already installed applications like Python, Ruby or NodeJS on your existing OS, you can go for the Quickstart package. All the tools and their environments are localized and isolated to the application folder of J1
Quickstart and should not interfere with already installed programs and their ressources. Simply by setting some environment variables, the system you've prepared already for Jekyll
will be left untouched. And you're done in about 15 minutes.
An option?
Quickstarter packages¶ ↑
All Quickstarter packages contain the following packages:
-
Ruby language, version 2.5
-
NodeJS language, version 8.9.4
-
NPM, version 6.1.0
-
YARN, version 1.7.0
-
Nginx Web Server, version 1.13.3
-
OpenSSL, version 1.0.2 (LTS 2019)
Additionally, some selected addons are packed for faster setup repectively improved productivity.
-
bash helper scripts
-
control scripts to start and stop services
-
Text-based file manager (Windows platform only)
-
Simple text editor (Windows platform only)
Quickstarters for all platforms have very the same layout and most of the applications packed are the same (in terms of their versions). If you work on Windows, the working environment feels the same as if you are on MacOS or Linux. As a plus, if you go for a Quickstarter (first), the beginner's documentation and tutorials will be easier to read and you can immediately follow what is presented and catch faster the workflows used.
In short: for the very first steps exploring the wonderful world of creating web sites using Jekyll
and J1
, the Quickstarter will be helpfull.
It's on you.
Download a Quickstarter¶ ↑
Find your platform and version for the J1
Quickstarter package you need with the following table:
include::{includedir}/tables/100_quickstart_installation_packages.asciidoc[]
Note, for Windows only a 32bit version (x86_32) is available that can be used for 32 and 64bit versions of Windows. For MacOS and Linux, only 64bit versions (x86_64) are supported.
TIP: To check your OS (kernel) version on MacOS run run sw_vers at the commandline. On Linux run *uname -r* at the shell. On Windows, type ver at the command shell (cmd). It's *6 something* for Windows 7 and 8, and *10 something* on Windows 10.
System requirements¶ ↑
For all platforms, an __Intel__-based system is required. The minimum hardware you'll need:
-
Processor: 1 gigahertz (GHz) or faster CPU, dual-core
-
RAM: 2 gigabyte (GB) for 32-bit (Windows only) or 4 GB for 64-bit systems
-
Hard disk space: 1 GB
NOTE: For many tasks (NPM scripts), parallel processing is used to speed up the build processes. This cause a higher memory usage. Make sure the system hardware (or the virtual machine) used meets the minimal system requirements.
Install a Quickstarter¶ ↑
Installing a Quickstarter on all platforms is quite easy. Typically, a Quickstarter is used under non-priviliged accounts. Therefor, the installation is done using an non-priviliged user, *no root* access is needed for Unix-like system as MacOS or Linux. For Windows you must install the package unter Administrator priviliges for some (technical) reasons.
Install on Windows¶ ↑
To install (and use) the Quickstarter on Windows, you need Administrator priviliges - via **U**ser **A**ccount **C**ontrol (UAC) at least. The installer process will fail, if the installation is started as an non-priviliged user.
.Missing Administrator priviliges imageblock::pages/downloads/quickstarter/100_installation/100_non_admin_install.png[]
- NOTE
-
¶ ↑
You need Administrator priviliges to install and run the Quickstarter development system because some tasks:
-
installation: adding a system-wide environment variable J1_HOME
-
run-time: installing, starting and stopping services
can be done on Windows as an member of the *Administrator Group* only. It is not recommended to run the Quickstarter under the Administrator account but you need to have the priviliges to *run as* an administrator. For private desktop installation this should *always possible* via UAC. On business (company) PC it depends. You can use
J1
Quickstarter if you are granted to work with *admin rights*.¶ ↑
Locate the installer file you've downloaded previously (j1_quickstart_setup_x86_32.exe) using an Windows Explorer (File Manager) and right click on that file. From the context menu, use *Run as administrator*. The installer will start correctly:
.Installer for
J1
Quickstart imageblock::pages/downloads/quickstarter/100_installation/110_admin_install_success.png[]The installation steps a quite straight forward. Follow the steps of the installer wizard and you're done in a couple of minutes. Expected run-time is about 10 to 15 minutes, depending on your systems hardware performance.
WARNING: You can install
J1
Quickstart in any folder of your choice but *do not use* a folder that contains spaces. Because of the unified folder layout Windows is using, for some languages a folder seems to have *no spaces* like Programme for the German localized version. The (unified) folder to install programs on Windows is *Program Files* containing a space and is mapped to Programme for the German version. Under the hood, the folder *Program Files* has spaces and will cause trouble if you install using this directory. For many cross-platform products developed on Unix-like systems as Linux, folders using spaces will cause unforeseeable failures accessing files and folders. On Windows it is recommended to use the root folder of a drive like *C:J1_QuickStart* or *D:J1_QuickStart* to make sure that the folder has *no spaces*.What needs to be done next? Go for <<setup-the-quickstart-enviroment>>
Setup the environment¶ ↑
On Windows platform run *J1 Consoles*, your best friend next times. Simply click on the icon named *J1 Consoles* placed on your desktop. Additionally a program group *J1 Quickstart* has been created for you that contains a link as well.
J1
Consoles (or Consoles for short) is based on ConEmu, a flexible configurable console and terminal manager for Windows. If Consoles is started, a single tab is opened: the *file manager*. It's look-and-feel is quite like the (good old) _Norton Commander_ - or _Midnight Commander_ on Unix platforms..Consoles on Windows imageblock::pages/downloads/quickstarter/100_installation/120_j1_consoles.png[]
For your better orientation, the most important parts for the next steps explained in more detail:
-
The *file manager* has a split screen (A and B) for different folders
to manage
-
Drops 1 and 2 are pointing to the *start folders* - 1 is the
base (installation) directory of
J1
Quickstart, 2 the web root folder where the web site will reside.-
The console manager can have *multiple tabs* (consoles) for different tasks
to do. Drop 3 points to the file manager tab. Additional tabs|consoles can be opened at the (very) small caret drop 4 is pointing to.
First, open 2 additional tabs (at the very little caret) marked by drop 4 for the next things to do:
Click on that little caret and open the 2 additional consoles and go for tab *J1 Shell* (the tab is numbered as <2>):
.J1 Consoles using multiple tabs, tab <2> the
J1
Shell imageblock::pages/downloads/quickstarter/100_installation/130_j1_console_j1_shell.png[]Type in j1init to start the update and installation process for the local installation of Ruby. Upgrading and installing Rubies will take a while - relax, have a break 8) …
TIP: Make use of *command expansion*. Type in 3 characters of a command like j1i for j1init and expand (the command) using the TAB key. Fast and easy, isn't it?.
NOTE: All commands of the Quickstarter using a prefix of j1 to not interfere with programs the same name. For example j1nginx is a helper to manage and control the Web Server Nginx. Because the name of the executeable of the Web Server is nginx, the correspondend helper j1nginx is prepended by j1 to not name conflict with it's binary.
If j1init is started all Rubies needed for the Quickstarter environment are being installed for you. First, the Ruby package management RubyGems (and the CLI gem) is being upgraded to its latest versions. You'll see something like this with the console:
- source, sh
Update RubyGems … Successfully installed rubygems-update-2.6.7 1 gem installed Install Gem Bundler … Successfully installed bundler-1.15.3 1 gem installed Install
J1
Ruby Gems …J1
Rubies installed successfullyJ1
Quickstart is ready to useHappy Jekylling!
From now, you're prepared to step in the world of
Jekyll
. A fresh RubyGem environment and current Rubies are in place with your Quickstarter. That's for the boring part.Now the thrilling part: go for <<first-jekyll-web>> to create your (very?) first
Jekyll
Web!Install on MacOS and Linux¶ ↑
Installing the Quickstarter on Unix-like platforms is simple. The package is a *tar ball* that can be extracted elswhere into any arbitrary folder of your choice. BUT: the package should never be installed as root - use an non-priviliged user, your *personal account* for example.
TIP: For /path/to/parent_directory e.g. you can use your user *home directory* like: *-C $HOME* to install the Quickstarter in *$HOME/j1_quickstart*.
You can install
J1
Quickstart in any folder of your choice but you should *not use* a folder that contains spaces. This may cause unforeseeable failures accessing files and folder by some of the components, tools or 3rd party libraries of ruby or python. On other hand, typing or reading folder names having spaces like */this/is/my \ folder \ having \ spaces/* is not fun.The tar ball is packed relatively to the folder j1_quickstart. In other words: the tar ball contains a folder j1_quickstart already (to prevent mesh up files in folders).
- source, sh
$ mkdir -p /path/to/parent_directory $ tar -xzf j1_quickstart_setup_XXX_x86_64.tgz -C /path/to/parent_directory
Your
J1
Quickstart package is in place. What needs to be done next? Go for <<setup_on_unix>>, the chapter below.- [setup_on_unix]
-
Setup the environment¶ ↑
Only two steps are needed for Unix-like platforms to setup your environment completely. Open a simple terminal (console) and change (cd) to the Quickstarters installation folder.
The two steps for the *very first* start are:
. set the quickstarter environment . initialize
J1
Quickstart for the first startFirst, run the helper script set_env out of the etc folder (run the script dotted, so-called sourced) to set some environment variables needed with your current shell. You'll need some more shells - open at 2 additional console (shell) sessions the same way (dont't forget to source your shell by running the set_env script!).
Go for one of them and run:
- source, sh
$ . ./etc/set_env
The helper j1init supports you to do some very basic tasks with the the Quickstarter. Run the helper j1init with the option help or he to see more details what j1init can do:
.Options of the helper script j1init
- source, sh
$ j1init he
Usage: j1init {all|check|status|print-env} Usage: j1init {bundle-install|bundle-test|bundle-clean|bundle-remove} Usage: j1init {gems-remove} Usage: j1init {clean-log|clean-force} Usage: j1init {help} all|al: (Re-)Initilize the Quickstarter. Compiles and installs Ruby and all Rubies needed. Useful only for setup. Be carefull using this option! check|ck: Run sanity checks for all J1 Quickstart components status|st: Display state of all Quickstarter deamons (RUNNING|STOPPED) print-env|ev: Display current environment bundle-install|bi: Install a bundle from current path bundle-test|bt: Integrity tests of a bundle from current path bundle-clean|bc: Delete all unused (older) gem referenced by a bundle from current path. Be carefull using this option! bundle-remove|br: Delete all gem referenced by a bundle from current path Be carefull using this option! gems-remove|gr: Delete ALL non-default gem from the system. Be carefull using this option! clean-log|cl: Delete all log files from ~/log folder clean-force|cf: Runs gems-remove + clean-log + delete all files from ~/var folder. Useful only for factory resets! help|he: Prints this help
To display your current environment, run:
- source, sh
$ j1init ev
.Environment displayed by j1init
- source, sh
j1init: found current quickstarter environment [ OK ] # ——————————————————————– # # Current quickstarter environment settings: # # GEM_HOME /home/xxxx/j1_quickstart/ruby/lib/ruby/gems/2.3.0 # NGINX_BIN /home/xxxx/j1_quickstart/nginx/bin # GEM_BIN /home/xxxx/j1_quickstart/ruby/lib/ruby/gems/2.3.0/bin # OPENSSL_HOME /home/xxxx/j1_quickstart/openSSL # NGINX_HOME /home/xxxx/j1_quickstart/nginx # OPENSSL_BIN /home/xxxx/j1_quickstart/openSSL/bin # PYTHON_LIB /home/xxxx/j1_quickstart/python/lib # PYTHON_BIN /home/xxxx/j1_quickstart/python/bin # NODE_BIN /home/xxxx/j1_quickstart/nodejs/bin # PYTHONHOME /home/xxxx/j1_quickstart/python # RUBY_HOME /home/xxxx/j1_quickstart/ruby # OPENSSL_CONF /home/xxxx/j1_quickstart/openSSL/openssl.cnf # J1_HOME /home/xxxx/j1_quickstart # RUBY_BIN /home/xxxx/j1_quickstart/ruby/bin # NODE_MOD_BIN /home/xxxx/j1_quickstart/nodejs/lib/node_modules/.bin # PYTHON_HOME /home/xxxx/j1_quickstart/python # NODE_HOME /home/xxxx/j1_quickstart/nodejs # # ——————————————————————–
The helper j1init support some simple sanity checks to check the integrity of the Quickstarter installed. Run a first check by:
- source, sh
$ j1init ck
You'll find that some checks are passed, but overall the integrity checks are FAILED. For good reasons. The environment ist set and some of the pre-installed applications are checked successful (PASSED).
.check results displayed by j1init
- source, sh
Status for quickstart: check environment [ PASSED ] Status for quickstart: checking python executeable [ PASSED ] Status for quickstart: checking node executeable [ PASSED ] Status for quickstart: checking npm executeable [ PASSED ] Status for quickstart: no ruby executeable found [ FAILED ] Status for quickstart: no bundler executeable found [ FAILED ] Status for quickstart: no gem executeable found [ FAILED ] Status for quickstart: integrity checks [ FAILED ]
But what is missing? All Ruby has test failed! For another good reason. There is (currently) no Ruby in place.
The most boring step is the initializatopn part: a fresh Ruby will be build and installed for your platform for best performance and stability. But compiling a fresh Ruby will take a while - anyway it is fully automated. Except the coffee you may need meanwhile :) …
Start the initialization by running:
- source, sh
$ j1init al
and the setup phase starts by an question - you see something like this:
- source, sh
This will RESET and (RE-)INSTALL the
J1
Quickstart installation … Are really you sure? (y/n)?
To start building you Ruby for the new Quickstarter, answer (**y**es). The setup phase starts immediately. You see something like this:
- source, sh
# Found your Quickstarter installed at: /home/xxxx/j1_quickstart # # Platform detected as: linux. # Platform is supported. Continue processing ... # # Compiling and installing Ruby. This will take a while :| # Have a break this time :) # # Unzip Ruby sources to: /home/xxxx/j1_quickstart/_ruby_src_extracted ... # Unzip of Ruby sources finished successful. # # Prepare (configure) Ruby 2.3.4 for compilation ... # Ruby 2.3.4 configuration successful. # # Compile Ruby 2.3.4 ... # Ruby 2.3.4 compilation successful. ...
The setup phase will take up to 15 minutes, depending on the performance the hardware you're using. To have a look what's going on under the hood, you can monitor the setup process by tailing the Quickstarters logfile:
- source, sh
$ tail -f ./log/j1quickstart.log
All main steps of the initialization phase are logged to j1quickstart.log like:
.Logfile j1quickstart.log
- source, sh
- 2017-08-11 13:16:07
- INFO
- j1init
- Start initializing
J1
QuickStart
- Start initializing
- 2017-08-11 13:16:07
- INFO
- j1init
-
[unzip ruby sources to: …
- 2017-08-11 13:16:08
- INFO
- j1init
- configure ruby 2.3.4 for compilation
- 2017-08-11 13:18:17
- INFO
- j1init
- compile ruby 2.3.4
- 2017-08-11 13:25:18
- INFO
- j1init
- install ruby 2.3.4
- 2017-08-11 13:25:51
- INFO
- j1init
- Initializing j1init finished
- 2017-08-11 13:25:51
- INFO
- j1init
- bundle from … installed succesfully
- 2017-08-11 13:25:51
- INFO
- j1init
J1
Quickstarter init finished
If your setup reaches the line *J1 Quickstarter init finished* your done! All has been prepared for you by the setup phase. You should check, if the sytem is now set correctly. Re-run the *integrity check* again:
- source, sh
$ j1init ck
You see something like this:
- source, sh
Status for quickstart: check environment [ PASSED ] Status for quickstart: checking python executeable [ PASSED ] Status for quickstart: checking node executeable [ PASSED ] Status for quickstart: checking npm executeable [ PASSED ] Status for quickstart: checking ruby executeable [ PASSED ] Status for quickstart: checking bundler executeable [ PASSED ] Status for quickstart: checking gem executeable [ PASSED ] Status for quickstart: integrity checks [ PASSED ]
Welcome this stage. You can be sure that all went fine. Puuh, a lot stuff was done. Anyway, is is done!
NOTE: All commands of the Quickstarter using a prefix of j1 to not interfere with programs the same name. For example j1nginx is a helper to manage and control the Web Server Nginx. Because the name of the executeable of the Web Server is nginx, the correspondend helper j1nginx is prepended by j1.
You are veeery close to your new, fresh
Jekyll
Web. Go for the final step <<first-jekyll-web>> below to create one!Go, go, go!
- [first-jekyll-web]
-
Create a first
Jekyll
Web¶ ↑J1
Template is a so-called gem-based Template forJekyll
. What a hell does that mean? The templateJ1
is a Ruby gem! And you've already installed that gem for your work. No additional installing steps needed. And better: all gem-based templates are updated automatically if your bundle (the set of Rubies you're using for a project) gets updated.As a last check, display the name and version of
J1
Template installed. On Windows, type in the J1Shell (tab), on MacOS or Linux use the current shell you've started the initialization phase earlier:- source, sh
$ gem list ^j1_tem –local
*** LOCAL GEMS *** j1_template_mde_3 (0.1.5)
J1
Template comes with a skin styled by the Bootstrap framework (V3 for now) in an very special flavour: MDE. That means **M**aterial **D**esign **E**lements. That's what billion of people know and use with Android mobiles each and every day. And - yes it is: Google *Material Design* forJekyll
Webs. That sounds cool-
no it is hot, hot stuff!.
Now the trilling part. How long will (should) it take to create a well equipped starter Web, based on Bootstrap and Googles Material Design?
Fire up your Web in a minute!
Windows users should go to console (on tab) <3>, the
Jekyll
Shell, users on MacOS or Linux should go for one of the other shell opened and move to the to *web root* directory www:- source, sh
$ cd $J1_HOME/www
NOTE: Remember, users on MacOS and Linux needs to run set_env for all shells used to work with
Jekyll
andJ1
first..Jekyll Shell on tab <3> imageblock::pages/downloads/quickstarter/100_installation/140_j1_console_jekyll_shell.png[]
Now, let's rock your fresh, new Web.
J1
Template comes with a CLI to manage base tasks more ease. No surprise, the CLI forJ1
Template is: j1. One of the tasks supported by the j1 is to create a Web (scaffold) by the subcommand generate (for now: a starter web).Run in the *Jekyll Shell*, respectively in the console you are on the path J1_HOME/www. The steps to go for:
. generate a starter (scaffold) . change to the web root folder . fire up jekyll (as a server)
- source, sh
$ j1 generate starter $ cd starter $ jekyll s -i
Configuration file: / .. /www/starter/_config.yml Source: / .. /www/starter Destination: / .. /www/starter/_site Incremental build: enabled Generating... done in 3.456 seconds. Auto-regeneration: enabled for '/ .. /www/starter' Server address: http://localhost:33333/ Server running... press ctrl-c to stop.
Haha, your done. Your Web is ready to use. The line *Server address: localhost:33333/* gives the URL of the Web created and served. For quick access,
Jekyll
supports serving a Web using the build-in server Webrick.Users on MacOS or Linux may run from command line:
- source, sh
$ open localhost:33333/
Users on Windows go back to console <1> (the File Manager) and click on j1open. Your favorite browser should start showing your fresh *starter web* build by
J1
Template and generated and served by Jekyll:.J1 Starter Web imageblock::pages/downloads/quickstarter/100_installation/150_j1_starter_web.png[]
Voila, your first Web is alive!
Some interesting parts and features of
J1
Template are prepared to explore. Have a look, surfe the Web for pages, for already prepared examples for you.TIP:
Jekyll
, respectively the CLI jekyll can be stopped by typing <CTRL> + <C> in the console or shellJekyll
has been started.Have fun exploring your first
Jekyll
Web!What's next¶ ↑
It depends on you, friends! If you like what
Jekyll
andJ1
doing, or can do for you, the Kickstarter *Your Web in a Day* should the choice for going further.Yeah, a day sound a lot! What is a Kickstarter?
Simply spoken a tutorial. A very practical way to learn new things. A good mix of theory and practical work. At the end you'll have achived a lot. A really a good base for going further. You'll learn a bunch you should know in terms of Web technologies,
Jekyll
,J1
and how they can be used - without to be a specialist. And: all examples of *Your Web in a Day* are designed for *real world* usage, a good base for the Web you have on your minds.Or you experienced, the
Jekyll
way is not the best for your requirements. That will happen. That's not a desaster, a lot of of other ways for your success are open other ways. What decision you may have made: it's based on knowlegde. Not something guessed. That's important. For you and for theJ1
team as well.You're welcome for a journey, a good day off exploring interesting places in the world of
Jekyll
andJ1
. The Kickstarter offers a lot more about what a Quickstarter can do, introduce you in usingJekyll
, makes you confident using theJ1
Template for your personal Web.In short: the Kickstarter supports you to create and manage
Jekyll
Webs efficently. The tutorial helps you to modify the configuration of aJekyll
Web, makes you familiar using the template system ofJ1
, modify existing pages and explains how to create new pages and blogs (articles) for your personal needs.Interested? The doors are open at {web_in_a_day}[Your Web in a Day, window=“_blank”].
Happy Jekylling!
-
-