diff --git a/dev/README.md b/dev/README.md index 5025d25e9..f32040de6 100644 --- a/dev/README.md +++ b/dev/README.md @@ -3,15 +3,15 @@ It is possible to use Docker containers to test your code, but it is normally more convenient to simply run the repository webapp (`alfresco.war`) and Share webapp (`share.war`) in a tomcat instance. Options are also available to -apply selected AMPs +apply selected AMPs. ## Setting up your development environment Although it is possible to work on individual github projects, we recommend working on the `alfresco-community-repo`, `alfresco-community-share` and `acs-community-packaging` -in a single Intellij IDEA project. They depend on each other and typically you +in a single Intellij IDEA project. They depend on each other and typically you will want to make changes to all of them if you are changing the repository code. -~~~ +~~~bash mkdir work cd work git clone git@github.com:Alfresco/alfresco-community-repo.git @@ -24,10 +24,10 @@ There are a set of aliases to help with building. You may find them useful, as t of the code base and will save you lots of typing. Aliases ending in `D` provide Maven commands for building local Docker images. The AMPS environment variable will be of -interest, if you wish to build AMPs included in the repo and share projects. +interest, if you wish to build AMPs included in the repo and share projects. The `aliases` file includes a more detailed description. -~~~ +~~~bash source acs-community-packaging/dev/aliases ~~~ @@ -37,14 +37,13 @@ pom.xml files of each downstream project so that they reference the SNAPSHOT ver upstream projects. To help do this see the `acs-community-packaging` project's `scripts/dev/linkPoms.sh` and `scripts/dev/unlinkPoms.sh` scripts. -~~~ +~~~bash sh acs-community-packaging/scripts/dev/linkPoms.sh ~~~ -## Build the alfresco-community-repo project -Build the `alfresco-community-repo` projects (if you have not -done so already), so that your changes are in the community alfresco.war file. -~~~ +## Build the Repo project +Build the `alfresco-community-repo` projects, so that your changes are in the community alfresco.war file. +~~~bash # The `comR` alias includes the following commands: cd alfresco-community-repo mvn clean install -DskipTests=true -Dversion.edition=Community @@ -52,10 +51,10 @@ cd .. ~~~ ## Build the Share project -Build the `alfresco-community-share` project (if you have not done so already), so that your -changes are in the community share.war file, which also depends on your `alfresco-community-repo` project version. -~~~ -# The `entS` alias is the same as the following commands: +Build the `alfresco-community-share` project, so that your changes are in +the community share.war file, which also depends on your `alfresco-community-repo` project version. +~~~bash +# The `comS` alias is the same as the following commands: cd alfresco-community-share mvn clean install -DskipTests -Dmaven.javadoc.skip=true cd .. @@ -64,9 +63,9 @@ cd .. ## Docker test environment The repository code will need to talk to other ACS components, such as a database, message queue and transformers. The simplest way to create these, is to use the `docker-compose.yml` file in the `dev` directory. -~~~ +~~~bash # The `envUp` alias is the same as the following commands. Run these in a new terminal session, or add a `-d` flag to -the `docker compose` command. +# the `docker compose` command. cd acs-community-packaging docker compose -f dev/docker-compose.yml up Creating dev_activemq_1 ... done @@ -79,7 +78,7 @@ cd .. ## Alfresco global properties and Log4j Set any alfresco-global.properties or log4j properties you may need in the following files. They will be copied -to the `dev/dev-acs-amps-overlay/target` directory. Other customisations may also be placed in the `extension` directory. +to the `dev/dev-acs-amps-overlay/target` directory. Other customisations may also be placed in the `extension` directory. ~~~ dev/dev-tomcat/src/main/tomcat/shared/classes/alfresco/extension/custom-log4j2.properties dev/dev-tomcat/src/main/tomcat/shared/classes/alfresco-global.properties @@ -88,11 +87,11 @@ dev/dev-tomcat/src/main/tomcat/shared/classes/alfresco-global.properties ## Tomcat Create the development tomcat environment, apply AMPs on top of the repository code, and run tomcat. The `run` profile is what starts tomcat. The `withShare` applies -the Share services AMP and adds the `share.war` to tomcat. +the Share services AMP and adds the `share.war` to tomcat. Once started, you will be able to access Share on `http://localhost:8080/share` and various repository endpoints via `http://localhost:8080/alfresco/`. `comT` is an alias for the following command and `comTDebug` will allow a debugger to be attached. -~~~ +~~~bash # The alias comT is the same as the following commands: cd acs-community-packaging mvn clean install -Prun -rf dev @@ -112,7 +111,7 @@ cd .. If you kill the tomcat instance (^C) and wish to restart it, use the following command or the `comO` alias, or `comODebug` to attach a debugger. -~~~ +~~~bash mvn install -Prun,withShare -rf dev-acs-amps-overlay ~~~ @@ -122,7 +121,7 @@ When finished, kill the tomcat instance and stop the Docker instances. You will remove the Docker containers, as you will need a clean database if you are going to issue another `mvn clean install` command. If you started `docker compose` in a separate terminal session, simply use `^C` or if you used a `-d` flag, use `docker compose -f dev/docker-compose.yml stop`. -~~~ +~~~bash ^C ... Stopped 'sysAdmin' subsystem, ID: [sysAdmin, default] @@ -142,3 +141,9 @@ Any changes made to alfresco-global properties or log4j will not be picked up, u directly edit `dev/dev-acs-amps-overlay/target/dev-instance/tomcat/shared/classes/alfresco/extension/custom-log4j2.properties` and `dev/dev-acs-amps-overlay/target/dev-instance/tomcat/shared/classes/alfresco-global.properties`, but they will be thrown away on the next `mvn clean`. + +## Helpful links + +- [alfresco-community-repo](https://github.com/Alfresco/alfresco-community-repo) +- [alfresco-community-share](https://github.com/Alfresco/alfresco-community-share) +- [acs-community-packaging](https://github.com/Alfresco/acs-community-packaging)