evernode landing page

When you enter the image name, you can append extra information (AFTER the :version part.)

we use -- which to be clear, is two dashes. this separates commands, and values.

now this extra information MUST start with --, even if you have not stated a version,

The things you can state are:

--peer--[value] port controls
--user--[value]
--gptcp1--[value]
--gpudp1--[value]
--gptcp2--[value]
--gpudp2--[value]
--env1--[KEY]-[VALUE]environment variables, be careful here as the KEY and VALUE is only separated with one dash -
--env2--[KEY]-[VALUE]where we use a number, you can add as many as you wish, be careful as no number can have a different function
--sec1--[name] this adds additional secret paths, you can add many --secX (see FAQ secret section for more info)
--vol1--[name] this adds additional volume/paths to the image
--domain--[domainname.com] when using your OWN doman (see FAQ web hosting section for more details)
--subdomian--[name] to use a subdomain of this evernode
--contract--true using "true" will force the hotpocket contract (as this gets substituted to "run /contract"), you can add your own command to run custom entrypoints (as this overrides the images default), or --false will force no additional commands so it uses image defaults
--ssl--false this forces the type of incoming connection that is accepted, to be a http:// (externally)
--proxyssl--false will make the connection from the internal proxy to the instance use http://
--dns--false will force the DNS system to ONLY query other evernodes for SSL files (so it will never call LetsEncrypt)
--modsec--false will turn of mod security protection that the proxy adds by default.(useful for hosting sites, especially ones based on WordPress)
--security--high or alias --sec--high this controls the security level thats applied to the instance, --none no auth layer enabled at all, --low auth layer enable, but no key protection, --mid auth layer with auto key protection, --high auth layer restricted to a manual unlock only.

Notes: You can add these in any order, and as many as you want to change.If you don't state these, then the default will be used.

currently there is a 128 Character limit

when docker pulls the image, it uses the stated image (and the version) ONLY, and ignores text starting at the 1st -- (this feature enables the use of configuration when using STOCK images).

Use ONLY alpha numeric characters (a-z A-Z and 0-9) no spaces, with the additional characters of, fullstop ., underscores _, and dashes -

there is also a handy character substitutions available;

3 fullstops ... to a dollar-sign$
2 fullstops.. to a dash -
3 underscores ___ to a slash /
and 2 underscores __ to a "space"

(these substitutions are applied in this order)

Basic example using a stock image.

jgraph/drawio:latest--gptcp1--8443

This maps the "general TCP port 1" to the internal port of 8443.

and as we used the general port 1 (gptcp1), which gets a routed to the default domain that is assigned (this can be used WITHOUT :port) this can be accessed externally on just the domain.

Advanced example (Minecraft server):

itzg/docker--minecraft-server:latest--user--25565--gptcp1--19133--env1--EULA-TRUE

so this links 2 of the given external ports to the defaulted internal ports that this image uses (the default minecraft port)

and also sets environment EULA=TRUE which for this image auto accepts the EULA terms

Advanced example using stock datagram image:

svetekllc/datagram:1.1.4--contract--run__....__..key__somenumbersforpublickey--gpudp1--51820

so this uses a contract command with character substitutions to start a run command on start up run -- key somenumbersforpublickey

along with opening internal port 51820 to the assigned external general UDP port 1

So yes you can use this type of evernode (evrPanel enabled) to directly host a website using a plain domain (no port numbers needed to be suffixed),
this works via routing the domain you request or are given, to the general TCP port (gptcp1), via a proxy that is installed infront of the evernode already.

So depending on the docker image that you use, will depend what port you should assign to the internal "gptcp1" for the link/port-forwarder feature to work

For example: using a image that has a web server inside, like a draw.io image, you would specify --gptcp1--8443 as port 8443 is the port that is used internally for that web server,
then the given assigned external port for evernodes gptcp1 for the instance gets passed to this internal TCP port (only one port (the gptcp1 port) is linked/proxied to the domain).
so here it is effectively equivalent to the stock docker command -p 443:8443

You have 2 choices of domain type. if none is selected then you will get one assigned,

1, you can assign a subdomain to your instance, with --subdomain--customname, this will then create and route customname.thisevernodesdomain.here as a working url to your instance. by routing it to the assigned (gptcp1) general TCP port 1 (what ever the assigned external tcp port 1 is given for your instance).

2, you can specify --domain--yourdomain.com to use your OWN domain, which then the specified domain gets routed to the (gptcp1) general TCP port 1 (what ever the assigned external tcp port 1 is given for your instance is).

To unable the use of YOUR domains on an evernode you will need to alter you domain settings:

Set "A" record(s) for each IP of the evernode(s) you want to use.
Set "NS" record(s) to subdomain "_acme-challenge." entering the domain for every evernode you want to use.
Set a "TXT" record to the root of your domain, of the instances public key.

Notes: We use the TXT record to protect your domain, so ONLY the instance that YOU create can be tied to YOUR domain, and the NS record on the subdomain _acme-challenge. so we can use DNS-01 method of getting SSL files for your domain.

SSL/TLS files explained.

ssl/tls files are generated and provided for your use, with many options and configuration.
when you 1st create your instance, ssl files first attempted to be obtained by checking other evernodes within your domain ns record, and downloaded from those, and if they don't have them, then its obtained via a DNS01 type method from official CA LetsEncrypt. using your other domain settings above. this method ensures rate limiting is at a minimum, even when setting up a cluster of evernodes using your single domain. there are two main settings, one if you DON'T need a SSL/TLS type connection (so you would access the domain with http://) you can state --ssl--false, useful when you OWN SSL proxy/platform is before the evernode.
and two, option --proxyssl--false, a common option, this is for when the internal connection from proxy to instance has no SSL setup, and is needed when you dont use the hosts ssl files in your instance.

these TLS files are provided and checked/updated every 3 days:

you can check the logs via the "SLL logs" button, where you can also force a re-check, or even delete them form the proxy for test or security reason.
files are provided at;

/contract/tls/cert.pem
/contract/tls/privkey.pem
/contract/tls/chain.pem
/contract/tls/fullchain.pem
/contract/tls/domain_ssl_update.log

And just a FYI: The "hosts" TLS/SSL files are still provided at:

/contract/cfg/tlscert.pem
/contract/cfg/tlskey.pem

website hosting example:

everweb/webcbuilder:latest--domain--yourdomain.com

uses the image everweb/webcbuilder for website hosting, and use your own domain (yourdomain.com) for the address

Yes, you can use docker secret paths within your images /run/secrets/name

there are 4 default secrets that are created on all instances, which can be used, and are pre populated as placeholder-only initially

These are the default secrets that are applied if none are stated:

user
pass
url
key

and any additional secrets are added according to the, --secX found in image name.

these secrets are set AFTER the image is running, via this landing page.(remember these options/features are only available if you are logged in for that instance)
you use the drop down select menu to select the secret you want to set, and submit your new value.
remember, your secrets can ONLY be set, and not read.

Security is important here, so by default when you use this site to update a secret, 1st a request API is sent, and the docker-build hash file values, along with a key pairing check from the evernode itself is sent back.
if ANY of these fail, then security is questionable, and the (encrypted) secret is not then sent. this check can be overridden via the "CheckHash" toggle, which is YOUR decision to make. (toggle is provided for fallback, and testing)

ALSO of note here is the authorization plugin layer that is enabled by default, this is a docker Auth plugin, that blocks all suspicious docker commands, like exec, attach, cp.
you can check these Auth plugin logs via the "Auth logs" button, enabling you to see LIVE if the Auth layer is; 1, enabled and LIVE, 2, check exec command is blocked (checking logs after trying to run a command), compare with and without the --security--none option flag, as you can see Auth logs differ before and after events, as very hard to fake all these logs and outputs, along with correct time stamps.

type of security level is also important feature, on low, then swarm key that secrets depend on is not removed/encrypted, on mid the swarm key IS removed and encrypted with the API endpoint pairing, and instance key, and on high, its removed and ONLY encrypted with instance key, this forces any server reboots needing a manual swarm unlock (so that you can fully check if you trust the environment still, and you decide weather to unlock or not.

More in depth details: a POST request is made to the api endpoint of this evernode at /api with data field { randomKey: a-random-key, type: integrity } a reply with signature and hash file results is then sent back, with this signature (using random key and hash results), your client will verify this with the held public key.
without the evernode having the secret key, and a unmodified API, and docker build files, its signature cannot be verified with public key, and if they are not verified, then with those files not in a good state, so the secret is then not 100% safe, so is not sent.

the api file hash should be,
unknown

the docker build hash should be,
unknown

and the public key for the key pair check is,
unknown

Using secrets variables:

cat /run/secrets/user

please use best practices handling these secrets in scripts, only use them in memory, and clear memory after use, never write them to file.

you can use cat /run/secrets/user within the "execute" form on landing page (if --debug--true is set of course)

Yes, these evernodes do support multiple image registries beyond Docker Hub (https://hub.docker.com/)
you do this by prefixing the alternative source address.
The most popular alternative being GitHub Container Registry (GHCR), where you would need to prefix with ghcr.io
when using additional registries, they cannot have any form of login requirement, for example Gitlab needs a API key for it to work,
also of note, LinuxServer.io type images, (these are images with custom init system (s6-overlay) in the layers, which try to chown /dev/console during layer registration) are converted by default.
but here are 5 good registries that are public, and work, (with examples);

AWS ECR Public — public.ecr.aws/project/image:tag

Chainguard — cgr.dev/chainguard/image:tag

Github Container Registry — ghcr.io/project/image:tag

Microsoft Container Registry - mcr.microsoft.com/project/image:tag

Quay.io (Red Hat) — quay.io/project/image:tag

Using AWS ECR public:

yes this is a fully working image from AWS ECR public registry you can try, is a simple nginx image.
see how we are also using the port config, as this image has port 8080 setup as the listening port,
then this image is not using any ssl files internally, so we need to force it to use no ssl for proxy to instance link,
and finally we also forcing it to use the images entrypoint with --contract--false. (as run binary doesn't exist in this image, so would fail with run error).

public.ecr.aws/nginx/nginx:latest--gptcp1--80--proxyssl--false--contract--false

Using Chainguards more security centered registry:

yes this is a fully working image from Chainguard you can try, is a non-root nginx image.
see how we are also using the port config, as this image has port 8080 setup as the listening port,
and also this image is not using any ssl files internally, so we need to force it to use no ssl for proxy to instance link,
and finally we also forcing it to use the images entrypoint with --contract--false. (as run binary doesn't exist in this image, so would fail with run error)

cgr.dev/chainguard/nginx:latest--gptcp1--8080--proxyssl--false--contract--false

Using githubs GHCR:

yes this is a fully working image from GHCR you can try, is a simple hello world site.
see how we are also using the port config, as this image has port 8080 setup as the listening port,
and also this image is not using any ssl files internally, so we need to force it to use no ssl for proxy to instance link.

ghcr.io/infrastructure-as-code/hello-world--gptcp1--8080--proxyssl--false

Using Microsoft MCR:

yes this is a fully working image from MCR you can try, is a basic ASP net app type sample webserver.
see how we are also using the port config, as this image has port 8080 setup as the listening port,
and also this image is not using any ssl files internally, so we need to force it to use no ssl for proxy to instance link.

mcr.microsoft.com/dotnet/samples:aspnetapp--gptcp1--8080--proxyssl--false

Using quay (redhat):

yes this is a fully working image from quay.io(redhat) you can try, is a full prometheus webserver.
see how we are also using the port config, as this image has port 9090 setup as the listening port,
also this image is not using any ssl files internally, so we using --proxyssl--false,
and also forcing it to use the images entrypoint with --contract--false.

quay.io/prometheus/prometheus:latest--gptcp1--9090--proxyssl--false--contract--false

Loading host...

... 📋

Frequently Asked Questions