Offline installs and mirrors
This page is for administrators and hosts whose servers have no outgoing internet access, or who want every installation to use a tested copy of the packages. It explains how the installer behaves without the package server, how to prepare an offline install, and how to run a mirror.
Contents
- What the installer does without the server
- Offline install, step by step
- A local index.xml
- Mirroring a release folder
- Pointing installations at the mirror
- Keeping a mirror current
- Related pages
What the installer does without the server
The behavior comes from kernel/setup/steps/ezstep_site_types.php:
| Situation | Setup wizard | Kickstarter, exp:install |
|---|---|---|
The index cannot be downloaded, var/storage/packages/7x/index.xml exists | that file is used instead, with no error | the same |
The index cannot be downloaded, no local index.xml | "Retrieving remote site packages list failed. You may upload packages manually."; the imported site packages are still listed | the imported site package is used when all its required packages are imported; otherwise the step stops |
| A required package is not imported and cannot be downloaded | the step stops with an error naming the package | the same |
| Everything is imported | nothing is downloaded for the dependencies | nothing is downloaded |
So the reliable way to install offline is to import every package first. The kickstarter's documentation says the same: "When the index cannot be read, a package already in the local repository is used if all its requirements are imported (an offline install)" (The kickstarter, 6.4).
Note
A dry run (exp:install --dry-run, exp:kickstarter run --dry-run) always downloads the site package and its
requirements into the temporary repository var/storage/packages/dryrun/ to check them. It needs the package
server (or a mirror) even when the packages are imported (The kickstarter, 6.7).
Offline install, step by step
On a machine with internet access:
- Choose the site package, for example
sevenx_multisite_clean. - Download it and every package it requires, and their requirements in turn
(Downloading a package by hand). For
sevenx_multisitethese aresevenx_classesandsevenx_multisite_democontent. - Check each file (Check it).
On the offline server, after the code is in place:
Copy the
.ezpkgfiles to a folder of the installation, for examplevar/tmp/packages/.Import each one:
for f in var/tmp/packages/*.ezpkg; do php ezpm.php import "$f"; doneCheck that they are in
var/storage/packages/7x/:ls var/storage/packages/7x/Install as usual:
exp:install --package=sevenx_multisite_clean, the kickstarter with[site_types] Site_package=sevenx_multisite_clean, or the setup wizard, where the package appears as "Imported".Remove the copies in
var/tmp/packages/when the install is done.
A local index.xml
When the index cannot be downloaded, the setup looks for index.xml in the system repository, the folder of
[RepositorySettings] Vendor (var/storage/packages/7x/index.xml by default), and uses it as if it had been
downloaded. That is useful when the url attributes in it point to a server the offline machine can reach, such as
a mirror in your own network. It does not make packages appear by itself: an entry whose url cannot be reached
still fails when it is needed.
Warning
In the setup wizard a site package entry from an index replaces the imported copy in the list when the index
version is higher, and choosing it downloads the package again. A local index whose url cannot be reached can
therefore hide your imported site package. Keep the versions in a local index equal to or lower than those of the
imported packages, or use no local index.
Mirroring a release folder
A mirror is a copy of one release folder on a web server you control. Nothing is needed but static file serving.
From Git, with only the folder you need:
git clone --filter=blob:none --sparse https://github.com/se7enxweb/exponential.packages.exponential.earth.git
cd exponential.packages.exponential.earth
git sparse-checkout set exponential/6.0/6.0.15From the server, by its index:
base=https://exponential.packages.exponential.earth/exponential/6.0/6.0.15
mkdir -p mirror/6.0.15/thumbnails && cd mirror/6.0.15
curl -fsSLO "$base/index.xml"
grep -o ' url="[^"]*"' index.xml | cut -d'"' -f2 | xargs -n1 curl -fsSLO
grep -o 'thumbnail_url="[^"]*"' index.xml | cut -d'"' -f2 | (cd thumbnails && xargs -n1 curl -fsSLO)Then rewrite the addresses in the copied index.xml to your host, because every url in the original names the
public server:
sed -i 's#https://exponential.packages.exponential.earth/exponential/6.0/6.0.15/#https://packages.example.com/6.0/6.0.15/#g' index.xmlPublish the folder so that https://packages.example.com/6.0/6.0.15/index.xml and every file it names answer 200,
and check them (Checking an index). The 6.0.15 folder is about 87 MiB;
most of it is sevenx_multisite_democontent.ezpkg.
Pointing installations at the mirror
# settings/override/package.ini.append.php
[RepositorySettings]
RemotePackagesIndexURL=https://packages.example.com/6.0/6.0.15The setup wizard, the kickstarter, exp:install and ezupdate then use the mirror. ezupdate needs an https://
address. Details, including kickstart.ini and ezupdate's server list:
Package server settings and
Pointing a site at your package server.
Keeping a mirror current
Packages in a release folder are fixed in place on the public server: the file name stays, the content changes (How a release reaches the package server). To follow those fixes:
- with the Git mirror,
git pullin the clone, then run the address rewrite again onindex.xml; - with the download mirror, run the download again into a new folder, compare checksums, and swap the folders.
Whether a mirror should follow every fix or stay at a version you have tested is your choice; a host that installs many customer sites usually tests first.
Related pages
- Site packages: start here
- The package server
- When the package server cannot be reached
- Running your own package server
- The local package repository
- Site packages for hosts
- Free documentation: this page is free to copy, translate and improve under the GNU FDL 1.3.
Become an Exponential Partner
Partners share their information, provide funding, contribute back and develop the products with us, and that is how Exponential grows. A partner website and dashboard are planned for mid-2027: please become a partner today to speed up our growth rate and land new features faster.