getting_started.rst

Getting Started

Selecting the right version

Gluon's releases are managed using Git tags. If you are just getting started with Gluon we recommend to use the latest stable release of Gluon.

Take a look at the list of gluon releases and notice the latest release, e.g. v2021.1. Always get Gluon using git and don't try to download it as a Zip archive as the archive will be missing version information.

Please keep in mind that there is no "default Gluon" build; a site configuration is required to adjust Gluon to your needs. Due to new features being added (or sometimes being removed) the format of the site configuration changes slightly between releases. Please refer to our release notes for instructions to update an old site configuration to a newer release of Gluon.

An example configuration can be found in the Gluon repository at docs/site-example/.

Dependencies

To build Gluon, several packages need to be installed on the system. On a freshly installed Debian Stretch system the following packages are required:

• git (to get Gluon and other dependencies)
• subversion
• python3
• build-essential
• gawk
• unzip
• libncurses-dev (actually libncurses5-dev)
• libz-dev (actually zlib1g-dev)
• libssl-dev
• wget
• time (built-in time doesn't work)
• qemu-utils

We also provide a container environment that already tracks all these dependencies. It quickly gets you up and running, if you already have either Docker or Podman installed locally.

./scripts/container.sh

Building the images

To build Gluon, first check out the repository. Replace RELEASE with the version you'd like to checkout, e.g. v2021.1.

git clone https://github.com/freifunk-gluon/gluon.git gluon -b RELEASE

This command will create a directory named gluon/. It might also tell a scary message about being in a detached state. Don't panic! Everything's fine. Now, enter the freshly created directory:

cd gluon

It's time to add (or create) your site configuration. If you already have a site repository, just clone it:

git clone https://github.com/freifunk-alpha-centauri/site-ffac.git site

If you want to build a new site, create a new git repository site/:

mkdir site
cd site
git init

Copy site.conf, site.mk and i18n from docs/site-example:

cp ../docs/site-example/site.conf .
cp ../docs/site-example/site.mk .
cp -r ../docs/site-example/i18n .

Edit these files as you see fit and commit them into the site repository. Extensive documentation about the site configuration can be found at: :doc:`site`. The site directory should always be a git repository by itself; committing site-specific files to the Gluon main repository should be avoided, as it will make updates more complicated.

Next go back to the top-level Gluon directory and build Gluon[1]:

cd ..
make update                       # Get other repositories used by Gluon
make GLUON_TARGET=ath79-generic   # Build Gluon

In case of errors read the messages carefully and try to fix the stated issues (e.g. install missing tools not available or look for Troubleshooting in the wiki.

ath79-generic is the most common target and will generate images for most of the supported hardware. To see a complete list of supported targets, call make without setting GLUON_TARGET.

To build all targets use a loop like this:

for TARGET in $(make list-targets); do
  make GLUON_TARGET=$TARGET
done

You should generally reserve 5GB of disk space and additionally about 10GB for each GLUON_TARGET.

The built images can be found in the directory output/images. Of these, the factory images are to be used when flashing from the original firmware a device came with, and sysupgrade is to upgrade from other versions of Gluon or any other OpenWrt-based system.

Note: The images for some models are identical; to save disk space, symlinks are generated instead of multiple copies of the same image. If your webserver's configuration prohibits following symlinks, you can use the following command to resolve these links while copying the images:

cp -rL output/images /var/www

The directory output/debug contains a compressed kernel image for each architecture. These can be used for debugging and should be stored along with the images to allow debugging of kernel problems on devices in the field. See :ref:`Debugging <dev-debugging-kernel-oops>` for more information.

Footnotes

[1]

make update only needs to be called again after updating the Gluon repository (using git pull or similar) or after changing branches, not for each build. Running it more often than necessary is undesirable, as the update will take some time, and may undo manual modifications of the external repositories while developing on Gluon. See :ref:`working-with-repositories` for more information.