This is the repository for the Zero-OS Hub website. It contains all the source code needed to make the public Zero-OS Hub website.
You can use GitHub Package directly: docker pull ghcr.io/threefoldtech/0-hub:master
Here are some point you need to run the hub:
/hub/src/config.py
with your configuration file/public
with your target public directories/workdir
with your target temporary directory/var/run/docker.sock
to be able to run docker converterRegarding configuration, here are some requirement:
zflist-bin
have to be or unset or set to: /usr/bin/zflist
(it's part of the image)
Dockerfile can be found on deployment
directory.
The Zero OS Hub allows you to do multiple things.
The hub is mainly there to gives an easy way to distribute flist files. Flist are database of metadata you can use in any Zero-OS container/vm.
In order to publish easily your files, you can upload a .tar.gz
and the hub will convert it automatically to a flist
and store the contents in the hub backend. After that you can use your flist directly on a container.
In order to reduce the maintenance of your images, products, etc. flist allows you to keep your different products and files separately and then merge them with another flist to make it usable without keeping the system up-to-date.
Example: there is an official ubuntu 16.04
flist image, you can make a flist which contains your application files
and then merge your flist with ubuntu, so the resulting flist is your product on the last version of ubunbu.
You don't need to take care about the base system yourself, just merge it with the one provided.
You can convert a docker image (eg: busybox
, ubuntu
, fedora
, couchdb
, ...) to a flist directly from
the backend, this allows you to use your existing docker image in our infrastructure out-of-the-box.
In addition with the hub-client (a side product) you can upload efficiently contents of file to make the backend up-to-date and upload a self-made flist. This allows you to do all the jobs yourself and gives you the full control of the chain. The only restriction is that the contents of the files you host on the flist needs to exists on the backend, otherwise your flist will be rejected.
All the operations on the hub needs to be done via a 3bot
(default) or itsyou.online
(deprecated) authentication.
Only downloading a flist can be done anonymously.
The hub host a basic REST API which can gives you some informations about flists, renaming them, remove them, etc.
To use authenticated endpoints, you need to provide a itsyou.online valid jwt
via Authorization: bearer <jwt>
header.
This jwt
can contains special memberof
to allows you cross-repository actions.
If your jwt
contains memberof, you can choose which user you want to use by specifying cookie active-user
.
See example below.
/api/flist
(GET)
/api/repositories
(GET)
/api/fileslist
(GET)
/api/flist/<repository>
(GET)
filename
, size
, updated
date and type
(regular, symlink, taglink) and optionally target
if it's a link./api/flist/<repository>/<flist>
(GET, INFO)
/api/flist/<repository>/<flist>/light
(GET)
/api/flist/<repository>/<flist>/taglink
(GET)
taglink
(link to a tag)/api/flist/<repository>/tags/<tag>
(GET)
/api/flist/me
(GET)
/api/flist/me/<flist>
(GET, DELETE)
/api/flist/<your-repository>/<flist>
/api/flist/me/<source>/link/<linkname>
(GET)
linkname
pointing to source
/api/flist/me/<linkname>/crosslink/<repository>/<sourcename>
(GET)
linkname
pointing to repository/sourcename
/api/flist/me/<source>/rename/<destination>
(GET)
source
to destination
/api/flist/me/promote/<sourcerepo>/<sourcefile>/<localname>
(GET)
sourcerepo/sourcefile
to your [local-repository]/localname
file/api/flist/me/upload
(POST)
.tar.gz
archive and convert it to an flistfile
form attribute/api/flist/me/upload-flist
(POST)
.flist
file and store itfile
form attribute/api/flist/me/merge/<target>
(POST)
repository/file
) as POST body/api/flist/me/docker
(POST)
image
form argument with docker-image name/api/flist/me/<tagname>/<name>/tag/<repository>/<flist>
(GET, DELETE)
repository/flist
in user tag tagname
with name name
name
from tagname
, if tag become empty, tag is removed/api/flist/me/<name>/crosstag/<repository>/<tagname>
(GET, DELETE)
name
inside your repository, pointing to repository/tag
Simple example how to upload to the hub in command line. Your token can be generated on the website.
curl -H "Authorization: bearer ...token..." -X POST -F file=@my-local-archive.tar.gz \
https://hub.grid.tf/api/flist/me/upload
Simple example how to use all feature to do some flist promotion. In this case, let assume:
user1
member-of
field for userX
in his jwtuser2/my-app-0.1.0
flist to userX/official-app-0.1.0
curl -b "active-user=userX;" -H "Authorization: bearer ...token..." \
"https://hub.grid.tf/api/flist/me/promote/user2/my-app-0.1.0/official-app-0.1.0"
Creation of flists are made using 0-flist and storage backend is 0-db. You need both of them working before getting a working hub.
In order to deploy your own hub, you need a working 0-flist
binary. You can see in deployment/deploy.sh
script how to compile it.
Alternatively, you can just download a precompiled version from 0-flist release page.
Copy the src/config.py.sample
file to src/config.py
, the file itself is well documented, then you can start the server:
cd src
python flist-uploader.py
To run latest hub, you need Flask >2.0. We recommend using Ubuntu 22.04.
apt-get install python3-flask python3-requests python3-jose python3-nacl \
python3-redis python3-docker python3-pytoml