Installing your own add-on: a module, theme or language from an archive
The two switches, inspection and installation, what is checked in the archive, common reasons for refusal and how an archive signed by Nex1on differs.
Your own module, theme or language (a .zip file built with the commands module:pack, theme:pack, language:pack or by hand) is installed on a site from one page: Add-ons → Modules → Install from archive. An archive is someone else's code that then runs on your server, so everything is done with care: only the owner can install, every step needs a password, and at first the archive is only inspected.
Two switches
The install page has two switches. They are shared by modules, themes and language packs.
| Switch | What it does |
|---|---|
| Install from archive | off by default. While it is off, upload and install answer “not found”, and the page shows only the switch itself. The owner turns it on with the “Turn on” button and a password. Turn it on only if you know where the archives will come from |
| Allow unsigned archives | off by default. Without it only archives signed by Nex1on are installed. Your own archives have no signature, so for them the switch must be on; for other people's archives, do not turn it on |
Two steps
- Inspection. Choose what you are installing: “Module”, “Theme” or “Language pack”, upload the .zip file (up to 20 MB), enter your password and press “Inspect”. The archive is unpacked into a temporary closed folder, its description is read and the signature is checked. Nothing is installed or run. In reply you get the “What is in the archive” report: the name and version, the number of files and size, the signature (“Signed by Nex1on” or “Unsigned”) and, if the same thing is already installed, what will be replaced.
- Installation. Tick “I understand the code in this archive will run on my server” (for a language pack: that visitors will read the texts), enter your password and press “Install”. The inspection is valid for 15 minutes and only for you; before installing, the files are checked once more, and if they have changed in the meantime, the installation refuses.
Installation puts only files in place. The module stays off and its migrations are not run; the theme is not activated; the language stays off. Next:
| What you installed | What to do |
|---|---|
| module | “Add-ons → Modules”, the “Install and enable” button on its card. Back up the database before enabling: enabling runs the module's code with the same rights as the site |
| theme | “Design → Themes”, “Make active” |
| language pack | “Languages and texts → Languages”, “Turn on” on the language |
What is checked in the archive
| Check | Limit or rule |
|---|---|
| size | archive up to 20 MB, no more than 2000 files, unpacked no more than 100 MB, a single file no more than 20 MB; an “inflating” archive (compression of more than a hundred times) is rejected |
| file names | only Latin letters, digits, dot, underscore and hyphen; no spaces or Cyrillic, no longer than 200 characters; the name does not start with a dot (.gitignore, .DS_Store are not allowed) and does not match a name reserved in Windows (con, nul, aux…); no duplicates |
| links and special files | there must be no symbolic links or special files in the archive |
| file types | php, json, md, txt, html, xml, csv, css, js, png, jpg, jpeg, gif, webp, ico, woff, woff2, and also license, readme, notice, changelog without an extension. svg images only in an archive signed by Nex1on |
| PHP | only in the folders src, views, database, demo and as the file routes.php in the root; a theme without a Nex1on signature has no PHP at all |
| description | there is a module.json or theme.json (for a language, language.json); the name in it matches the folder name; the name is not taken by a built-in module and is not a reserved word |
| language pack | the archive holds only the language description and translation files in JSON; strings without markup or dangerous links |
| signature | the signature matches the archive contents, the key is not revoked |
| replacement | an enabled version cannot be replaced (turn it off first); an older version or an archive with a different signature only with a separate confirmation; a built-in module is replaced only by a newer archive signed by Nex1on |
Code is not run during inspection or installation: the files just lie on disk. The commands module:pack and theme:pack do the same contents check in advance, so an archive they built usually arrives at this point whole.
Common reasons for refusal
| What it says | What to do |
|---|---|
| “Turn on install from archive first.” | turn on the first switch (owner, password) |
| “The archive is not signed by Nex1on: allow “unsigned” and tick “I understand”.” | for your own archive, turn on the second switch and tick “I understand…”; better not to install someone else's unsigned archive |
| “A file name in the archive is not allowed.” | rename the file in Latin letters without spaces, remove files that start with a dot (.gitignore, .DS_Store) |
| “A file type in the archive is not allowed.” | remove the file (svg, ttf, exe, a zip inside the archive, a file without an extension) or replace it with png, webp, woff2 |
| “A PHP file in a place where it is not allowed.” | move the PHP to src, views, database or demo; only routes.php is allowed in the root |
| “A theme without a signature cannot contain PHP files.” | rewrite the templates with tags; a theme needs no PHP |
| “module.json / theme.json is missing or wrong.” | the file must lie in the root of the module folder inside the archive; check the JSON |
| “The folder in the archive is not named like the module.” | the folder name inside the archive and name in the description must be the same |
| “This name is taken.” | choose another name: built-in modules and reserved words (admin, api, core…) are taken |
| “A built-in module can be replaced only by a newer archive signed by Nex1on.” | your own module must not be named like a built-in one |
| “This version is enabled: turn it off first.” | turn the module off or switch to another theme, and install again |
| “The version is older than the installed one” or “The signature differs from the previous one” | if this is intentional, tick the confirmation and upload the archive again |
| “The archive is too big”, “Too many files”, “The archive expands too much” | remove the excess from the archive: samples, picture sources, copies |
| “The file does not open as a zip.” | rebuild the archive as an ordinary zip (not rar, not 7z) |
| “The inspection expired or is not yours” | an inspection lives for 15 minutes: upload the archive again |
| “Too often: no more than five times an hour.” | wait; this limit is there on purpose |
| “The signature does not match the contents” | the archive was changed after signing or the signature is foreign: take the original |
How an archive signed by Nex1on differs
An archive built and signed by us (from the add-on catalogue or sent by us) is installed at once: the signature is checked, and we know what is inside. Only in such an archive are svg and PHP in a theme allowed. Your own archive has no signature: we do not know who built it or what is inside, and its code gets full access to the site and the database. So such an archive is installed only if the owner has separately allowed “unsigned” and has ticked in the report that they understand the risk. If the server has nothing to verify signatures with, signed archives are not accepted.
What remains after installation
- The old version, if there was one, is kept in
storage/backups; you can roll back by uploading the previous archive with the “I confirm replacing” tick. - The installation is written to the log, and the site owners get an email with the name, version and signature.
How to write what you are installing: Your own module, Your own theme, Your own language and language pack. The general reference for this feature is the article Installing a module or theme from an archive.