Wojciech Kapcia (Tigase) opened 1 week ago
-
Yes, I agree here. Docker compose and we also need images ready to use. Some environments do not allow building, like my home server for example. I think images are already being created and uploaded onto 1dev, so, this might be just matter of preparing right docker compose file with images location.
-
Wojciech,
I provide two versions of docker compose files: one for development in $TOP/deploy/docker/docker-compose.yml and other is a release docker compose (what you call "fire and forget" docker compose) that is driven by sensible defaults in the compose file itself and which is also based on .env: this is in $TOP/release folder.
You are using the development docker compose which will build from src instead of pulling pre-built images off the registry.
The release note clearly states what needs to be done. If you had followed it, you would have found a different problem - a minor typo in the sztabctl command which I am fixing now. I will create a new release 1.9.2 to fix this typo.
-
rksuma@Ramakrishnans-MacBook-Pro ~ % rm -fr sztab-staging rksuma@Ramakrishnans-MacBook-Pro ~ % mkdir sztab-staging rksuma@Ramakrishnans-MacBook-Pro ~ % cd !!: zsh: illegal modifier: \n rksuma@Ramakrishnans-MacBook-Pro ~ % cd sztab-staging rksuma@Ramakrishnans-MacBook-Pro sztab-staging % git clone https://tigase.dev/sztab.git Cloning into 'sztab'... remote: Enumerating objects: 6175, done. remote: Counting objects: 100% (6175/6175), done. remote: Compressing objects: 100% (4897/4897), done. remote: Total 6175 (delta 3291), reused 1057 (delta 529), pack-reused 0 Receiving objects: 100% (6175/6175), 92.17 MiB | 5.62 MiB/s, done. Resolving deltas: 100% (3291/3291), done. rksuma@Ramakrishnans-MacBook-Pro sztab-staging % cd release chmod +x sztabctl cd: no such file or directory: release chmod: sztabctl: No such file or directory rksuma@Ramakrishnans-MacBook-Pro sztab-staging % cd sztab rksuma@Ramakrishnans-MacBook-Pro sztab % git checkout v1.9.1 Note: switching to 'v1.9.1'. You are in 'detached HEAD' state. You can look around, make experimental changes and commit them, and you can discard any commits you make in this state without impacting any branches by switching back to a branch. If you want to create a new branch to retain commits you create, you may do so (now or later) by using -c with the switch command. Example: git switch -c <new-branch-name> Or undo this operation with: git switch - Turn off this advice by setting config variable advice.detachedHead to false HEAD is now at 7b9a818 chore(frontend): stabilize production Dockerfile for 1.9.1 rksuma@Ramakrishnans-MacBook-Pro sztab % cd release rksuma@Ramakrishnans-MacBook-Pro release % chmod +x sztabctl rksuma@Ramakrishnans-MacBook-Pro release % ./sztabctl --help Usage: sztabctl --run sztabctl --down sztabctl --logs sztabctl --status sztabctl --urls Notes: - Must be executed from within the release directory. - Uses: docker-compose-release.yml rksuma@Ramakrishnans-MacBook-Pro release % ./sztabctl --run Starting Sztab... [+] Running 6/6 ✔ Network release_sztab-net Created 0.1s ✔ Container release-sztabina-1 Started 0.7s ✔ Container sztab-db Healthy 11.2s ✔ Container sztab-backend Started 11.3s ✔ Container sztab-ui Started 11.3s ✔ Container caddy Started 11.4s Sztab started. Access URLs: UI : http://localhost Backend : http://localhost/api Git : http://localhost/git/{repo}.git rksuma@Ramakrishnans-MacBook-Pro release % -
rk@tigase.net changed state to 'In Progress' 1 week ago
Previous Value Current Value Open
In Progress
-
Previous Value Current Value In Progress
Closed
-
Previous Value Current Value Closed
Open
-
-
-
Previous Value Current Value Open
Won't Fix
-
I provide two versions of docker compose files: one for development in $TOP/deploy/docker/docker-compose.yml and other is a release docker compose (what you call "fire and forget" docker compose) that is driven by sensible defaults in the compose file itself and which is also based on .env: this is in $TOP/release folder.
… yet it's not mentioned at all in the readme: https://tigase.dev/sztab/~files/wolnosc/README.md
The release note clearly states what needs to be done. If you had followed it, you would have found a different problem - a minor typo in the sztabctl command which I am fixing now. I will create a new release 1.9.2 to fix this typo.
Do we have a documentation website deployed with those notes? No. Do we have a dedicated "release page" akin to github releases (in 1dev it would be builds: https://tigase.dev/sztab/~builds) to which one could refer to? Also no.
What's more - Release Notes indicates information about what's new in the version and less so deployment instructions? I would argue that would be one of the less obvious places to check… Not to mention that, to be absolutely frank - I had no idea what you are referring to exactly. Then I checked the emails and voila - there they were…
Taking into consideration "regular user that wants to try the software" would be useful without sounding dimissive at my failed attempt to try the software. For you the project structure and location of all information may be obvious, but please try puting yourself in shoes of someone not familiar with the project. What I did:
- opened main repository page (because there is no other): https://tigase.dev/sztab/~files/
- searched for "compose" (because I'm looking for the easier way to run it)
- I see "Running Locally (Full Stack)" section described as "Sztab can now be brought up locally in one step using Docker Compose." which points to:
cd deploy/docker docker compose up --buildwhich at no point explicitly states that it's "development environment" (yes, there is
--buildparameter but given no other mention of alternative compose deployment one assumes it's the only one)Looking at the file list you see:
deploy … releaseand thinking logically where would you look for information related to deployment?
Maybe the aformentioned "clear information in release note" is not that clear and obvious after all, to warrant, rather uncalled-for, comment?
Looking at the mentioned "release notes" (https://tigase.dev/sztab/~files/wolnosc/docs/release/1.9.1/README_FIRST.md) I'm not sure, they are as "clear and concise" either; let's disect that:
- I'm not sure that involving git into the whole thing is needed (docker compose is just a yaml file, you can grab relevant file via curl which is suggested in the majority of docker compose deployments)
- the release notes are for version 1.9.1 yet in the document you say: "git checkout wolnosc" (and later on "Expected: 1.9.1") -- this would give you latest version so if your development moves forward it would not be about version 1.9.1 [sidenote: why main branch is called
wolnoscand not typicalmasterormain? it's quite confusing for no apparent reason) - why do you use
chmod +x sztabctl? It's possible to set executable flag for a file tracked in git - why do we even have
sztabctlexecutable? I read the purpose section in https://tigase.dev/sztab/~files/wolnosc/docs/release/1.9.1/sztabctl.md#1-purpose, but it looks like just adding complexity layer on top of docker compose for the sake of… complexity itself; whole "Usage" section could simply give relevantdocker composecommands thatsztabctlis just a wrapper of… (not to mention that you yourself noted a type-o in it…)
Compare this "workflow" with forgejo (putting aside that it's the page and not the repo view, but the former can mimic quite well the latter). After you click "Get forgejo" you go to https://forgejo.org/releases/ where you can see release notes (https://codeberg.org/forgejo/forgejo/src/branch/forgejo/release-notes-published/14.0.2.md) which don't mention anything about installation, just changes and actuall "installation" page (https://forgejo.org/docs/latest/admin/installation/) with binary and docker option, and the latter (https://forgejo.org/docs/latest/admin/installation/docker/) giving you simplest possible docker-compose to use…
Possible improvement suggestions (although you deemed it "wontfix"):
- in the main READ.ME adding another section right after "features" named "Quick start" with basic:
cd release docker compose up -d?
- possibly shuffle the things a bit and put "for use" compose files in "deployment" and those for development in… "dev(elopment)" directory?
-
Regarding:
“… yet it’s not mentioned at all in the readme”
With every release I send a short announcement that begins with:
Please start here: https://tigase.dev/sztab/~files/wolnosc/docs/release/1.9.1/README_FIRST.md
README_FIRST explicitly directs the reader to the ./release folder, which contains the release artifacts, including the non-build Docker Compose file.
The fire-and-forget compose therefore exists and is part of the documented release workflow.
Even when browsing the repository directly, the top-level ./release directory is visible and contains the release compose file.
⸻
Regarding:
"Do we have a documentation website deployed with those notes?"
For each release, README_FIRST is the canonical entry point for installation of that version. It serves that role in lieu of a separate documentation website.
If there is a desire to duplicate release installation instructions into the root README, that can be discussed as a documentation improvement. However, that is distinct from the original defect statement.
⸻
Regarding the defect resolution:
The original defect states:
“We should have docker compose in a form that doesn’t require building, just docker compose up, pulling latest image and starting the application.”
This capability already exists in ./release.
Therefore, the defect statement is factually incorrect. The issue was marked “won’t fix” because OneDev does not provide a more precise resolution state such as “invalid” or “not a defect.” The accurate classification is that there is nothing to fix.
Some documentation corrections you pointed out (e.g., typos) are valid and have been addressed in 1.9.3.
-
(can you use quoting with
>? it helps with the comment flow… there is "quote" button at the end of the comment or, if you reply by email, it should be quoted automatically)Regarding:
“… yet it’s not mentioned at all in the readme”
With every release I send a short announcement that begins with:
Please start here: https://tigase.dev/sztab/~files/wolnosc/docs/release/1.9.1/README_FIRST.md
README_FIRST explicitly directs the reader to the ./release folder, which contains the release artifacts, including the non-build Docker Compose file.
OK, but my comment was from the perspective of someone trying to check the project and landing on the main repository page. This is what should be the MAIN entry point and focus, not "Release notes" which:
- you probably won't send to absolutely whole world
- release notes (at least for me) suggest: "information that version was released, what was changed and any actions that you should take manually if upgrading"
IMHO expectation that anyone stumbling on the main project page should first go on a hunt for release notes because what's presented on the main page is basically incorrect is quite odd…
The fire-and-forget compose therefore exists and is part of the documented release workflow.
Yes, it does exsists. I'd argue that the "documented release workflow" is invalid…
Even when browsing the repository directly, the top-level ./release directory is visible and contains the release compose file.
Probably it's "me problem" but as I suggested in my previous message: for me
./releasewould contain anything related to performing the release of the application and./deploymentwould contain information related to how to depoy it…⸻
Regarding:
"Do we have a documentation website deployed with those notes?"
For each release, README_FIRST is the canonical entry point for installation of that version. It serves that role in lieu of a separate documentation website.
Which is quite weird take becase said
README_FIRSTis burried deep inside folder structure so even if you put more caps and exclamation marks noone would effectively "read it first" when it's burried so deep.If there is a desire to duplicate release installation instructions into the root README, that can be discussed as a documentation improvement. However, that is distinct from the original defect statement.
This is quite a nitpick… Alas, I'll rephrase the title (and I'll update the original message) of the issue to avoid multiplying tasks about same issue, which is basically: "hard to discover easy deployment means"
Regarding the defect resolution:
The original defect states:
“We should have docker compose in a form that doesn’t require building, just docker compose up, pulling latest image and starting the application.”
This capability already exists in ./release.
Therefore, the defect statement is factually incorrect. The issue was marked “won’t fix” because OneDev does not provide a more precise resolution state such as “invalid” or “not a defect.” The accurate classification is that there is nothing to fix.
Some documentation corrections you pointed out (e.g., typos) are valid and have been addressed in 1.9.3.
I'm not even sure how to parse this comment. It would be nice to have certain flexibility in issues as means of discussion instead of outright rejecting them…
If you are so adamant about semantics and hairsplitting, the title says: "Basic docker-compose should be "fire and forget"". The basic docker compose file, as shown in the most user-facing place (
README.MDfile) is not "fire-and-forget" which makes the issue very much relevant.To that end, the issue is about:
- making information about quick & easy deployment of the application by the Regular User the most prominent information
- information about "dev environment" should be an afterthough and mentioned in the "dev section"
In the end while the project is for developers intended audience cares about using it and not developing it…
-
Previous Value Current Value Won't Fix
Open
-
Previous Value Current Value Basic docker-compose should be "fire and forget"
Easy user-deployment information (docker-compose) should be prominent/the only one on the repository landing page.
| Type |
Task
|
| Priority |
Normal
|
| Assignee | |
| Version |
none
|
| Sprints |
n/a
|
| Customer |
n/a
|
README.MD) to avoid confussionOriginal issue for context