Is your feature request related to a problem?

Rewrite the quickstart in order to have an end-to-end example.

Solution you'd like

Currently the quickstart, while needed to be concise, is lacking prerequisites. The goal is to have, in one page, an end-to-end working example.

And at the end, a next steps section should be added, so the reader is provided directions.

Alternatives you've considered

N/A

Anything else?

No response

As agreed with @nunix it would be nice to have a basic documentation for Epinio docker extension.

Existing documenation only here https://www.suse.com/c/kubernetes-in-docker-desktop-just-got-easier-with-epinio/
More info here epinio/epinio#1784

Is there an existing issue for this?

• I have searched the existing issues

Current Behavior

The documentation contains no page describing how to upgrade epinio (server, and cli binary)

Note: The cli binary can be handled by referencing the existing page describing how to install it.

Expected Behavior

To have a page describing the upgrade process.

Steps To Reproduce

No response

Environment

No response

Logs

No response

Anything else?

No response

@catherineluse suggested the following improvements to the epinio.io front page:

• put the epinio push command at the top, so you can see it without scrolling down. The top says in words "go from Code to URL in one step" but it isn't clear what that step is, as the epinio push isn't actually mentioned until the bottom of the page.
• we should mention that you don't need to build the application container image yourself
• we should mention that it comes with a UI
• The install steps on the landing page have too many steps, so at a glance it looks like a lot. I think the steps should be more like:
  1. Get access to a Kubernetes cluster
  2. Install Epinio in the cluster with Helm
  3. Log in to the cluster with epinio login
  4. Do epinio push (or whatever is needed to get to epinio push.)
     It should just link to docs for details instead of trying to put everything on the landing page

We should also mention a newer (supported) version of cert-manager (if at all)

If Epinio is uninstalled, all components deployed in the default namespace workspace will be removed too.
We should warn the users about such a difference between the default namespace and the ones they might create.
Likely in the uninstall page.

Follow up of: epinio/epinio#1099

Following of epinio/epinio#1373 (comment)

For now, we should probably just accept the fact that the internal registry won't work on Azure and document that. We also need to change our tests on Azure to use a proper registry.

Following of epinio/epinio#1116 (comment)

Is there an existing issue for this?

• I have searched the existing issues

Current Behavior

Page https://epinio.io/ , under section "Install Epinio in under 5 minutes",
under item 6. Learn more in the Installation, which resolves to https://docs.epinio.io/installation/installation.html - comes up with page not found

Expected Behavior

should resolve to https://docs.epinio.io/installation

Steps To Reproduce

Follow https://epinio.io/

Environment

No response

Logs

No response

Anything else?

No response

We should test and document a configuration where the control plane is being exposed through one ingress class and the workload is exposed through another. This can help increase security by allowing for control plane to be on an internal only network instead of exposing to the internet.

Solution requirements:

• Traffic is split between different domains
• Developers should be easily able to specify which ingress/network to expose app on
• App exports should work as expected

Out of scope:

• Epinio would not provide ingress or IngressClasses
• Epinio would not control any networking before ingress (security groups for example)

We want our docs to be:

• searchable
• versioned
• cool looking
• easily updatable
• possible to translate (if community picks this up)

With Traefik installed in other namespaces (kube-system with k3d for example), this command will not work.

kubectl  get svc -n traefik -o jsonpath="{.items[0].status.loadBalancer.ingress[0]}"

A more resilient way would be look in any namespace:

kubectl get svc -A -o jsonpath="{.items[*].status.loadBalancer.ingress[*]}"

Is there an existing issue for this?

• I have searched the existing issues

Current Behavior

The documentation is missing information about changes in the app chart as used by the epinio server.
See epinio/epinio#1629 and PR epinio/epinio#1652

Is there an existing issue for this?

• I have searched the existing issues

Current Behavior

Hi,

If the staging process is long (ie. npm install in NodeJS) the CLI and UI may exprerience websocket timeout.

In case of nginx used as Ingress or Proxy you have to increase the read timeout

apiVersion: extensions/v1beta1
kind: Ingress
metadata:
  name: nginx-ingress
  namespace: production
  annotations:
    kubernetes.io/ingress.class: "nginx"
    nginx.ingress.kubernetes.io/proxy-read-timeout: "360s"```

### Expected Behavior

_No response_

### Steps To Reproduce

_No response_

### Environment

```markdown
- OS: SLES
- Architecture: x86
- Epinio Version: 0.7.3
- Cluster:
  - Provider: Self RKE2
  - Options:
  - Kubernetes Version: 1.21

Logs

EpinioServer/streamer-to-websockets: "msg"="failed to write to websockets" "error"="write tcp 10.42.244.102:8030->192.168.102.23:50482: write: broken pipe"

Anything else?

No response

Is your feature request related to a problem?

Some users might be more security conscious than others so it would be useful to include some writing about how to improve the security of Epinio.

Solution you'd like

We can use several of the features already built into Epinio to dramatically improve security:

• Separate ingresses for control plane vs workload to allow for DMZ style networking
• mTLS with linkerd (or other mesh)
• NeuVector
  • Both networking and container scanning
• Kubewarden to only allow scheduling of Epinio workloads
• Custom app template with NetworkPolicies along with a "deny-all" base policy

I'm sure there are more places where we can increase our security stance as well

Alternatives you've considered

No response

Anything else?

No response

There are outdated: https://docs.epinio.io/howtos/setup-external-s3.html

We need instructions on how to do the same using the helm chart.

Tip: This is how it works: https://github.com/epinio/epinio/blob/main/acceptance/install/scenario4_test.go#L46-L53

As commented here: https://rancher-users.slack.com/archives/C021TRREKPT/p1651220685751849?thread_ts=1651075000.125439&cid=C021TRREKPT

on RancherDesktop 1.3.0 on Linux, in order to use 127.0.0.1.omg.howdoi.website, one needs to run this:

sudo sysctl -w net.ipv4.ip_unprivileged_port_start=443

so that host's port 443 is mapped to the cluster's 443. We should document this.

The docs should include the information from here: https://github.com/epinio/ui/blob/dev/README.md

Is your feature request related to a problem?

Issue epinio/epinio#1635 is IMHO clearly rooted in missing documentation.

The submitter was unaware of the target command and actually edited the settings file directly to change the target namespace.
Looking over the docs I see only the manpage for target in the reference block.
And the description there is relatively short.

Solution you'd like

I believe that we need a How to work with multiple namespaces document.

Alternatives you've considered

No response

Anything else?

epinio/epinio#1635

Is your feature request related to a problem?

The current docs structure is based on the Divio documentation structure, however some areas have started to be mixed up.

Solution you'd like

Re-apply the Divio documentation structure to the docs and have the different topics re-ordered.

Also, whenever possible, add a Next Steps section to docs in order to provide the reader with a "suggested reading path".

Alternatives you've considered

N/A

Anything else?

No response

The only supported way to install Epinio is now the single helm chart:

• epinio/helm-charts#101
• https://artifacthub.io/packages/helm/epinio/epinio

Out documenation site still describes the installation using the epinio-installer chart.

Acceptance Criteria

• Epinio documentation site only describes installation using the single chart
• Epinio repositories (wikis, READMEs etc) only refer to the single chart
• The epinio-installer chart on ArtifactHub has a deprecation warning
• The epinio registry chart on ArtifactHub has a deprecation warning. The registry is now part of the single chart.
• The subtitle of the epinio chart is fixed: https://artifacthub.io/packages/helm/epinio/epinio (The Epinio component (without dependencies) is now wrong)

As we tested Epinio installation on top of Rancher Desktop (epinio/epinio#1116), it's a good time for updating doc about that process.

https://docs.epinio.io/installation/install_epinio_on_rancher_desktop.html

For example here: https://docs.epinio.io/installation/install_epinio_on_k3d.html#install-epinio-on-the-cluster

It's in many places

Going through the doc I've found this troubleshooting section:

Troubleshooting

While Kubernetes 1.22 is supported there is an issue when the container runtime is containerd > 1.5.6.
The pack cli is placing too much information into the image layers.
The relevant issue is: paketo-buildpacks/full-builder#415

The referenced issue is still open but it seems that it has been resolved.

The containerd issue was fixed and added to the v1.5.8.

Since containerd was updated in the v1.22.4 of k3s I guess we can assume that it's fixed and remove the troubleshooting section, or maybe reference to update to the 1.22.4, and update and close the paketo-buildpacks/full-builder#415 as well.

/cc @jimmykarily

Is there an existing issue for this?

• I have searched the existing issues

Current Behavior

This line of docu does not work
https://github.com/epinio/docs/blame/main/src/howtos/install_epinio_on_k3d.md#L24

Error in running this command

k3d cluster create epinio -p '80:80@server[0]' -p '443:443@server[0]'

gives

FATA[0000] failed to transform ports: Failed to parse node filters (with suffix): invalid format or empty subset in 'server[0]' 

I get pass by running

k3d cluster create epinio -p '80:80@loadbalancer' -p '443:443@loadbalancer'

Expected Behavior

k3d cluster being created

Steps To Reproduce

see above

Environment

- OS: Linux Ubuntu
- Architecture:
- Epinio Version: 0.6.1
- Cluster:
  - Provider:
  - Options:
  - Kubernetes Version:

Logs

NA

Anything else?

NA

Upstream mdBook will remove its google-analytics integration.
Instead downstream projects should put respective javascript code into theme/head.hbs

• download google-analytics code from Google
• create theme/head.hbs and add the analytics code there
• switch CI to use upstream mdBook

Tekton dependency has been removed. The docs still talk about Tekton.

Ref: epinio/epinio#1625

Epinio uses buildpacks primarily to build workloads.

Other projects have a lot of documentation around using specific buildpacks, for languages:

• https://docs.cloudfoundry.org/buildpacks/go/index.html

Others describe mainly how to use buildpacks:

• https://buildpacks.io/docs/app-developer-guide/build-an-app/
• https://dokku.com/docs/deployment/builders/cloud-native-buildpacks/
• https://dokku.com/docs/deployment/builders/herokuish-buildpacks/
• https://skaffold.dev/docs/pipeline-stages/builders/buildpacks/

When we make big changes in documentation (like switching to docusaurus for example), it's nice if we can see the result before we merge. netlify or similar could be useful here.

Acceptance Criteria

• When a PR is opened in epinio/docs there is a URL that serves the rendered result.

Is your feature request related to a problem?

We tell people that they can use our service marketplace to integrate with other providers, but this may not be as trivial as we assume.

Solution you'd like

Our docs should have an example of integration with the Crossplane AWS provider and a service like PostgreSQL in RDS. This should include any additional provider setup other than what Crossplane's getting started guide shows along with binding of the service to an app.

Alternatives you've considered

No response

Anything else?

I tried to get this working and ran into an issue where the secret that crossplane produces doesn't have the correct labels. A "hacky" way to fix this may be using a post-install hooks in helm that waits for the secret to exist then adds the appropriate labels. There is likely a better way to do this...

Is there an existing issue for this?

• I have searched the existing issues

Current Behavior

After 1.0.0 release some helm chart links are still poinint to 0.7.1 as can be seen:
https://docs.epinio.io/howtos/install_epinio_on_rancher_desktop

There are a few examples in the 'How to pages' but potentially can be more:

• https://docs.epinio.io/howtos/install_epinio_on_rancher
• https://docs.epinio.io/howtos/install_epinio_on_rke
• https://docs.epinio.io/howtos/install_epinio_on_k3s
• https://docs.epinio.io/howtos/install_epinio_on_rancher_desktop
• https://docs.epinio.io/howtos/install_epinio_on_k3d

Expected Behavior

They should point to 1.0.0 (24 Jun, 2022)

Steps To Reproduce

No response

Environment

- OS:
- Architecture:
- Epinio Version:
- Cluster:
  - Provider:
  - Options:
  - Kubernetes Version:

Logs

No response

Anything else?

No response

When we "un-hide" the epinio service command, we should add cli documentation for it (and swagger spec).

Depends on: epinio/epinio#1332

Is there an existing issue for this?

• I have searched the existing issues

Current Behavior

The link for System Requirements page is wrong in the Installation page.

This issue has been reported on Slack as follow:

Just a random heads-up: https://docs.epinio.io/installation/system_requirements.html returns 404 (linked from https://docs.epinio.io/installation/installation.html#prerequisites)

[ link ]

Expected Behavior

The link opens the System Requirements page.

Steps To Reproduce

1. Go to page https://docs.epinio.io/installation/installation.html#prerequisites
2. Click on the link "See system requirements"
3. Page not found is displayed

Environment

Docs issue affecting all browsers.

Logs

N/A

Anything else?

No response

Is your feature request related to a problem?

Add some docs for epinio/epinio#1926

Here? https://docs.epinio.io/howtos/setup_external_s3#authentication-through-an-iam-profile

Solution you'd like

No response

Alternatives you've considered

No response

Anything else?

No response

Alejandro Bonilla found RKE2 documentation https://docs.epinio.io/howtos/install_epinio_on_rke a bit confusing. According to him RKE2 is most important product we sell so we should polish it more.

Especially the part RKE2 Prerequisites related to Ingress where we don't mention RKE2 native nginx-ingress controller but describing something about MetalLB instead.

We should simplify that section and describe how to:

• expose epinio in a POC Lab env - internal IP/wild-card DNS
• expose epinio and its workload on Public Internet - by using node's EXTERNAL-IP assigned to internal nginx-ingress
  • find a way how can RKE2 assign EXTERNAL-IP to nodes
  • configure nginx-ingress to use that EXTERNAL-IP(s)
• expose epinio and its workload on Public Internet - by using some sort of external Load Balancer running on extra VM with a public IP/Domain(s) assingned
• (handle TLS certs - probably described elsewhere)
• install a storage provider/driver which is not preinstalled by default in RKE2 (k3s has local-path by default including a SC for it)

Another document related to DNS topic is https://docs.epinio.io/installation/dns_setup which should be revisited.

Tasks:

• #236
• #237

The helm chart tarball https://helm.traefik.io/traefik/traefik-10.3.4.tgz listed in the Traefik installation instructions no longer exists at that URL

When running an app on Minikube the following message appears on status:

failed to get replica details:`the server could not find the requested resource get pods.metrics.k8s.io) 

➜  ~ epinio app list           

🚢  Listing applications
Namespace: workspace

✔️  Epinio Applications:
| NAME |            CREATED            |             STATUS             |            ROUTES            | CONFIGURATIONS | STATUS DETAILS |
|------|-------------------------------|--------------------------------|------------------------------|----------------|----------------|
| app1 | 2023-01-18 16:09:02 +0100 CET | failed to get replica details: | app1.192.168.39.100.sslip.io |                |                |
|      |                               | the server could not find      |                              |                |                |
|      |                               | the requested resource (get    |                              |                |                |
|      |                               | pods.metrics.k8s.io)           |                              |                |                |

This can be corrected by adding:

minikube addons enable metrics-server

We should update https://docs.epinio.io/howtos/install_epinio_on_minikube accordingly

Our docs have a lot of outdated information. Let's fix what we can.

• Installation
• Explanations
• Howtos

#70

Already discussed with @nunix and @mmartin24

When you land on the documentation website, I find very confusing the way to get the installation instructions for Epinio.

You have to click on Installation to print the instructions.
As a user (and it already happened with newcomer), I would click on the down arrow next to installation and then, click on Install Epinio CLI because I see Install Epinio there.
And it will result with a bad experience because you will install the epinio CLI and it's useless without an epinio server instance.
I would prefer something like:

Installation 
    Install Epinio
    Install Epinio CLI

Now epinio is available on brew

• epinio/epinio#1306

We have to update the documentation to show how to do this.

Note: remember to document both the tap (to have the latest version) and the core installation method.

• https://github.com/epinio/homebrew-tap

• Update docs with installation from custom Epinio tap

Nice to have

It will be nice to use updatecli to update the links to the latest version, so the user will have a working link and avoid to look for the released versions.

PTAL

• updatecli/website#268
• https://github.com/updatecli/website/blob/master/updatecli/updatecli.d/installation.yaml#L25-L33

targets:
  download-url:
    name: 'Update Installation URL'
    kind: file
    spec:
      file: content/docs/prologue/installation.adoc
      matchPattern: 'https://github.com/updatecli/updatecli/releases/download/(.*)/'
      replacePattern: 'https://github.com/updatecli/updatecli/releases/download/{{ source "updatecli" }}/'
    scmID: default

Is your feature request related to a problem?

We are now adding in the stateful set template to the default epinio chart. This could cause confusion so we should document when to use one over the other.

Solution you'd like

No response

Alternatives you've considered

No response

Anything else?

No response

Is there an existing issue for this?

• I have searched the existing issues

Current Behavior

https://docs.epinio.io/blog/mdx-blog-post

The default blog posts are still in the repo.

Expected Behavior

No response

Steps To Reproduce

No response

Environment

- OS:
- Architecture:
- Epinio Version:
- Cluster:
  - Provider:
  - Options:
  - Kubernetes Version:

Logs

No response

Anything else?

No response

According to epinio/epinio#1954 user may define a ingressClass for workload only, this is probably not covered by documentation.

• Epinio itself and its Workload uses the default ingressClass if not defined by --set ingress.ingressClassName=traefik
• NEW in addition users may define also an ingressClass for epinio Workload only by --set server.ingressClassName=nginx

While going through the doc files it's hard to understand which file matches just from the name.

Since they are numbered paragraph I would suggest to rename files and folders with a prefixed number.
I've done this in the past and I found it useful.

i.e.:

At the moment the index is written like this:

- [Introduction](introduction.md)
- [Quick Start](tutorials/quickstart.md)
- [Installation](installation/installation.md)
  - [System Requirements](installation/system_requirements.md)
  - [Method 1: Install Epinio and automatically install dependencies](installation/install_epinio_auto.md)
  - [Method 2: Install Epinio and manually install dependencies](installation/install_epinio_manual.md)
  - [Install Epinio cli](installation/install_epinio_cli.md)
...

while the files are unordered

src/
├── installation/
│   ├── install_epinio_auto.md
│   ├── install_epinio_cli.min.md
│   ├── install_epinio_manual.md
│   ├── installation.md
│   └── system_requirements.md
├── tutorials/
│   └── quickstart.md
└── introduction.md

I would suggest to modify it like this:

src/
├── 01_tutorials/
│   └── 00_quickstart.md
├── 02_installation/
│   ├── 00_installation.md
│   ├── 01_system_requirements.md
│   ├── 02_install_epinio_auto.md
│   ├── 03_install_epinio_manual.md
│   └── 04_install_epinio_cli.min.md
└── 00_introduction.md

It was introduced here: epinio/epinio#496

This command epinio settings update-ca have to be called after downloading epinio binary and before calling epinio login ... otherwise user is getting an Error x509: signed by unknown authority when doing epinio push ...

Good place would be probably https://docs.epinio.io/tutorials/quickstart#login and also on the cli reference page https://docs.epinio.io/references/settings#commands

Note: Quite a bit of the servers' operation, namely around workloads, assumes the presence of a deployment resource, and/or, and/or ingress. To keep things simple enough now it is assumed that even a custom chart will provide these three resources.

Originally posted by @andreas-kupries in epinio/epinio#1224 (comment)

Is your feature request related to a problem?

While trying to install mirrorbits, the deployment failed and @enrichman suggested to add the file Procfile with the content set to web: mirrorbits where mirrorbits is the name of the binary.

Solution you'd like

I think we should add some documentation about it\

Alternatives you've considered

No response

Anything else?

No response

Is your feature request related to a problem? Please describe.
When doing a Minikube installation the need for setting a load balancer ip is not needed; however, when following the installation steps and being redirected to the installation page the next point after creating namespace traefik is:

export LOAD_BALANCER_IP=$(LOAD_BALANCER_IP:-) # Set this to the IP of your load balancer if you know that

I did not know what value to assigned and gave randomly the first one on the range; however this could have been skipped for minikube

Describe the solution you'd like
One solution could be add a comment like "Not needed for minikube installation" or "If you don't mind the loadbalancer giving you a random IP address, you can skip this option"
Another possibility could be explain better what this option is