-
Notifications
You must be signed in to change notification settings - Fork 24
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Merge pull request #566 from entando/ENDOC-546
ENDOC-546 build and publish a v5 bundle project
- Loading branch information
Showing
2 changed files
with
44 additions
and
178 deletions.
There are no files selected for viewing
185 changes: 37 additions & 148 deletions
185
vuepress/docs/next/tutorials/create/pb/publish-project-bundle.md
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,165 +1,54 @@ | ||
| --- | ||
| sidebarDepth: 2 | ||
| --- | ||
| # Build and Publish a Project Bundle | ||
| # Build and Publish a Bundle Project | ||
| ## Overview | ||
| This tutorial demonstrates how to deploy an existing Entando project directory into the [Local Hub](../../../docs/getting-started/concepts-overview.md#local-hub). This involves building a Docker image from your microservice, creating an Entando Bundle, checking your Bundle artifacts into Git, and deploying the Bundle into Kubernetes. | ||
| This tutorial describes how to deploy an existing Entando project directory into the [Local Hub](../../../docs/getting-started/concepts-overview.md#local-hub). Following the steps below will: | ||
|
|
||
| The Entando CLI (ent) automates many of the tasks involved in deploying an Entando Bundle, but you can also choose to perform these tasks manually. | ||
| - Build Docker images for the bundle and any microservices | ||
| - Push the Docker images to a Docker registry | ||
| - Apply the bundle custom resource to Kubernetes | ||
| - Install the bundle into an Entando Application | ||
|
|
||
| ## Prerequisites | ||
| * Use the [Entando CLI](../../../docs/getting-started/entando-cli.md#check-the-environment) to verify you have the prerequisites in place (e.g. Java, npm, git) | ||
| ``` sh | ||
| ent check-env develop | ||
| ``` | ||
| * Your Git credentials | ||
| * A Git repository | ||
| * An Entando instance | ||
| * An Entando project directory, either [developed by hand](./publish-simple-bundle.md) or [generated by the Entando Component Generator](../ms/generate-microservices-and-micro-frontends.md) | ||
|
|
||
| ## CLI Steps | ||
| The following steps make use of the Entando `ent prj` command and its publication system (pbs) convenience methods. See the [Manual Steps](#manual-steps) section below for a more detailed description of the underlying tasks. | ||
|
|
||
| 1. Build the project using the `ent prj` command. This saves you from having to build each part of the project individually. If you are using a project directory with just a bundle child directory (e.g. a bundle with hand-built components or exported from another environment), then there is nothing to build and you should skip this step. | ||
| ``` sh | ||
| ent prj build | ||
| ``` | ||
| ::: tip | ||
| The first run can take longer due to node downloads for any MFE widgets. You can use `ent prj fe-build` or `ent prj be-build` for subsequent runs to independently build just the frontend or backend components. | ||
|
|
||
| ::: | ||
|
|
||
| 2. Initialize the bundle directory | ||
| ``` sh | ||
| ent prj pbs-init | ||
| ``` | ||
|
|
||
| 3. Publish the build artifacts to GitHub and Docker Hub | ||
| ``` sh | ||
| ent prj pbs-publish | ||
| ``` | ||
|
|
||
| 4. Deploy the bundle into the ECR | ||
| ``` sh | ||
| ent prj deploy | ||
| ``` | ||
| Jump to [Install the Bundle into an Application](#install-the-bundle-into-an-application) below to finish installing your bundle. | ||
|
|
||
| ## Manual Steps | ||
|
|
||
| ### Build a Docker Image for Microservices | ||
| 1. Build the project from the project directory | ||
| ```sh | ||
| ./mvnw -Pprod clean package jib:dockerBuild | ||
| ```` | ||
|
|
||
| > **Note** | ||
| > | ||
| > By default, the organization used to generate the Docker image is `entando`. You can customize this value during project initialization by either changing the `pom.xml` file or providing the `-Djib.to.image=<org>/<name>:<version>` to the `jib:dockerBuild` command. | ||
|
|
||
| > **Note** | ||
| > | ||
| > The output image name is generated using the organization value defined during project initialization. You can override the provided values by altering the `pom.xml` file or by customizing the `-Djib.to.image` parameter used by the `./mvnw` command. | ||
| The Entando Bundle CLI tool (**ent bundle**) automates many of the tasks involved in deploying an Entando project bundle. | ||
|
|
||
| > **Warning** | ||
| > | ||
| > If you manually override the target image of the Docker build, remember to update the plugin metadata accordingly. | ||
|
|
||
| 2. View your image and tag | ||
| ``` sh | ||
| docker images | ||
| ``` | ||
| Output: | ||
| ``` | ||
| REPOSITORY TAG IMAGE ID CREATED SIZE | ||
| myusername/example-app 0.0.1-SNAPSHOT 4ec7f05b2b27 33 seconds ago 213MB | ||
| ``` | ||
| 3. Publish the Docker image to Docker repository (Docker Hub or equivalent). You may need to first login via `docker login`. | ||
| ```sh | ||
| docker push <name-of-the-image:tag> | ||
| ``` | ||
| For example: `docker push myusername/example-app:0.0.1-SNAPSHOT` | ||
|
|
||
| > **Note** | ||
| > | ||
| > All of the layers are pushed the first time you run this command, which takes time. Subsequent runs are much faster. | ||
| Output: | ||
| ``` | ||
| docker push myusername/example-app:0.0.1-SNAPSHOT | ||
| The push refers to repository [docker.io/myusername/example-app] | ||
| 545361404af4: Pushed | ||
| ... | ||
| f1b5933fe4b5: Pushed | ||
| 0.0.1-SNAPSHOT: digest: sha256:804b3b91b83094c45020b4748b344f7199e3a0b027f4f6f54109cbb3b8a1f867 size: 2626 | ||
| ``` | ||
|
|
||
| ### Build Your Bundle and Publish to Git | ||
| 1. Populate the bundle with the generated micro frontends using `./buildBundle.sh` or `npm run populate-bundle` | ||
| ```sh | ||
| ./buildBundle.sh | ||
| ``` | ||
|
|
||
| > **Important** | ||
| > It takes time to populate the bundle with micro frontends. You can watch the progress of this process on the console. | ||
| 2. The output of your bundle is in the top-level `bundle` directory of your microservice | ||
|
|
||
| 3. Commit your bundle files to Git, separate from the top-level project files | ||
| ``` sh | ||
| echo bundle >> .gitignore | ||
| cd bundle/ | ||
| git init | ||
| git add . | ||
| git commit -m "Init Git repository" | ||
| ``` | ||
|
|
||
| 4. Create a new Git repository, e.g. `my-bundle` | ||
|
|
||
| 5. Add your remote repository as origin and push the bundle | ||
| ``` sh | ||
| git remote add origin https://your/remote/repository.git | ||
| git push -u origin master | ||
| ``` | ||
| ## Prerequisites | ||
| * Verify dependencies with the [Entando CLI](../../../docs/getting-started/entando-cli.md#check-the-environment): `ent check-env develop` | ||
| * Authenticated Docker credentials | ||
| * A Docker repository | ||
| * A running Entando instance | ||
| * An Entando project directory. You can create this [from scratch](./publish-simple-bundle.md) or [with the Entando Component Generator](../ms/generate-microservices-and-micro-frontends.md). | ||
|
|
||
| 6. Publish a Git tag | ||
| ``` | ||
| git tag -a "v0.0.1" -m "My first tag" | ||
| git push --tags | ||
| ``` | ||
| ## Create and Deploy a Bundle Project | ||
|
|
||
| 7. Generate a custom resource for your bundle. Update the following command with your bundle name, namespace and repository URL. | ||
| The following steps leverage the Entando `ent bundle` command and its convenience methods. | ||
|
|
||
| ``` sh | ||
| ent bundler from-git --name=<bundle-name> --namespace=entando --repository=<your-repository-url> --dry-run > example-bundle.yaml | ||
| ``` | ||
| 1. From the root bundle directory, generate the Docker image: | ||
| ``` sh | ||
| ent bundle pack | ||
| ``` | ||
| This builds the bundle components and Docker images. | ||
|
|
||
| 8. Make your bundle available in Kubernetes | ||
| ``` | ||
| kubectl apply -f example-bundle.yaml -n entando | ||
| ``` | ||
| 2. Publish the Docker image to a Docker registry: | ||
| ``` sh | ||
| ent bundle publish | ||
| ``` | ||
|
|
||
| ## Install the Bundle into an Application | ||
| You can either install the bundle through the ent CLI or the `App Builder`. | ||
| ## Use the Entando CLI | ||
| 1. In your project folder, run the following command | ||
| ``` sh | ||
| ent prj install | ||
| ``` | ||
| 2. If you have already installed the bundle, you can use `--conflict-strategy` to adopt a strategy for existing components (CREATE, SKIP, OVERRIDE) | ||
| ``` sh | ||
| ent prj install --conflict-strategy=OVERRIDE | ||
| ``` | ||
| 3. Deploy the bundle to your Entando Application: | ||
| ``` sh | ||
| ent bundle deploy | ||
| ``` | ||
| Your bundle will appear in the Local Hub of your Entando instance, accessible from `App Builder` → `Hub`, and show a status of DEPLOYED. | ||
|
|
||
| > **Note** | ||
| > | ||
| > In the event of a timeout or pod failure, refer to the errors captured by the quickstart-cm-deployment and plugin deployer logs. | ||
| 4. Install the bundle in your Entando Application from `App Builder` → `Hub` or with the following command: | ||
| ``` sh | ||
| ent bundle install | ||
| ``` | ||
| Your bundle will now show a status of INSTALLED. | ||
|
|
||
| ## Use the App Builder | ||
| 1. Log into your App Builder and select `Hub` | ||
| ## Notes | ||
|
|
||
| 2. Find your bundle and select `Install` | ||
| The Entando Platform downloads and installs the Docker images for microservices and installs the micro frontends into the Entando Application. You can add micro frontend widgets to a page or page template provided by Entando, or to one you create yourself following the [Page Management tutorial](../../compose/page-management.md). | ||
|
|
||
| The Entando Platform downloads and installs the Docker image for your microservice and installs your micro frontends into the Entando Application. You can add these micro frontend widgets to the page(s) of your choice. You can either leverage a page provided by Entando or follow our [Page Management tutorial](../../compose/page-management.md) to create your own page or page template. Note that your page template must include the UX fragment `keycloak_auth` because an application based on the Entando Blueprint expects a user to be authenticated. | ||
| An application based on the Entando Blueprint expects a user to be authenticated. If your project bundle was generated using the Entando Component Generator, your widget can only be added to a page template that includes the UX fragment `keycloak_auth`. | ||
|
|
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters