Documentation Improvement - Replace the '<...>' placeholders by the real ones

[gitartpiano]

Cloning, building, running all worked I even created my account and login on my own Alexandrie server at 127.0.0.1:3000, all within a few minutes.

But for hours I cannot figure out from the provided documentation how to complete configuration of this server and how to configure a simple hello app (cargo new hello) to be able to publish to this server with cargo. Even if every parameter has descriptive names in the config file, I still don't know how to determine their values.

Please provide a specific working example.

The Replace the '<...>' placeholders by the real ones instructions are not helpful in
https://hirevo.github.io/alexandrie/getting-started.html

Otherwise congrats to the nice and very important work!

[gitartpiano]

This issue #44 offers some solution, but I don't want
Index hosted on private GitLab repo, I prefer index to be hosted by Alexandrie itself.

[Hirevo]

Hello !

I'm sorry about the struggle you encountered.
I tried to write sufficient amounts of docs to make the installation process as clear and painless as I could, but, as someone who always knew the project, it can be hard to properly put myself in the shoes of newcomers and not missing anything (because of a subtle assumption we happened to inadvertently make).
This kind of feedback is super valuable to improve these docs against these mistakes, so thank you for filing the issue.

I'll be pushing a PR to try to address this and explain the placeholders in more details.

In the meantime, to come back to your specific issue, the main question can be:
Is your index accessible through HTTP/HTTPS or SSH ?

The HTTP/HTTPS case is the one that should just work by following the README.
The SSH case can require the solution found in #44, which isn't really specific to GitLab, it should apply to any private index located behind an SSH-authenticated endpoint.
(But we have yet to document that part in the README and the book, that is definitely on me, sorry again about that)
As an example, we're using the SSH method in exactly this way in our automated end-to-end testing setup, you can try to take a look at how it configures things here and see if it matches your situation:
https://github.com/Hirevo/alexandrie/blob/master/e2e/images/runner/runner.sh#L72

[gitartpiano]

Is your index accessible through HTTP/HTTPS or SSH ?

Your question assumes that I already have an index, but as a newbie I don't.

But the tests (you pointed out with the link) contain valuable information, especially this file will help me set one up:
https://github.com/Hirevo/alexandrie/blob/master/e2e/images/index/init-repo.sh

What I was asking in bold, is all here in the tests now I think.

[gitartpiano]

The install/configure procedure I followed is documented as a script.
Before running it a git repo needs to be created for the crate-index. (I used gitlab).
The script will prompt for the URL of this repo, or optionally the URL can be specified as the argument for the script.

#!/bin/bash

alex_dir=~/alexandrie
crate_index_git_url=$1

while ! git ls-remote -h $crate_index_git_url
do
  read -p 'crate_index_git_url: ' crate_index_git_url
done

if ! curl --version
then
  sudo apt update
  sudo apt install -y curl
fi

if ! ~/.cargo/bin/rustup --version
then
  curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh -s -- -y --no-modify-path
else
  rustup update
fi

if [ -d "$alex_dir" ]
then
  cd "$alex_dir"
  git pull
else
  git clone https://github.com/Hirevo/alexandrie.git "$alex_dir"
  cd "$alex_dir"
fi

cargo build

mkdir -p crate-storage

if [ -d crate-index ]
then
  cd crate-index
  git pull
else
  git clone $crate_index_git_url crate-index
  cd crate-index
fi

if [ ! -f config.json ]
then
  cat >config.json <<EOF
{
    "dl": "http://$(hostname):3000/api/v1/crates/{crate}/{version}/download",
    "api": "http://$(hostname):3000",
    "allowed-registries": ["https://github.com/rust-lang/crates.io-index"]
}
EOF
  git add config.json
  git commit -m "add config.json"
  git push
fi

The myhello project's .cargo/config file:

[registries.my-registry]
index = "ssh://git@githostname.mydomain/gitusername/crate-index.git"

After logging in publish worked

cargo login --registry my-registry
cargo publish --registry my-registry

[Hirevo]

(Sorry for the delayed response)

Happy to hear that you were able to make progress, I've opened #70 to improve documentation around setting up the crate index, which, I have to agree, was notably overlooked.

As part of that PR, I have also integrated a slightly modified version of your script in the user guide, with a link to it from the project's README.
(link to the modified script in docs)
Such a script can indeed be useful and can make the process of getting started faster for newcomers.
Thank you very much for writing and sharing the script, it is a valuable thing to have available.

This issue is set to close automatically once #70 gets merged.
If you consider that the issue remains unaddressed by #70, feel free to say so (or re-open the issue if it got closed in-between).

[gitartpiano]

I have looked at the documentation updates, and agree to close this.