Thanks for this massive change ;-). I'll run it locally to check how it looks like.

From a first glance, the new server manual looks massive (and complicated). Do we really need that much theory there:

Speed and latency

Bandwidth – do you have enough?

Server types

Can't we assume that most people want to set up a private server if they go through this document?

Bandwidth use

That's a duplicate of content above

Starting a server

Finally ;-).

/wiki/Server-Linux That's a guide I personally would have preferred to see right away.

@ann0see

Thanks for this massive change ;-). I'll run it locally to check how it looks like.

This thread appears to be a good exercise for me to learn how things are done. What documentation is there for me to reconstruct how to follow what is happening in this thread? I am lost. I need a starting point.

I am certainly interested in having a server admin manual.

I think, you should run it locally. Do you know git? On which OS do you run? You should have a look at https://jekyllrb.com/docs/step-by-step/01-setup/ and install jekyll afterwards, you can

git clone gilgongo's repo: git clone [email protected]:gilgongo/jamuluswebsite

checkout the branch from which he made these changes:

git checkout adm-man

and then run jekyll via

jekyll serve

and browse to http://127.0.0.1:4000/ via a web-browser to see the site.

If you need more help, I'd suggest to open a thread on the GH discussions or ask on DC

@ann0see Thanks for the pointers. I will first try to install it under my macOS. It would be the most convenient if that works. Would that be a bad idea?

Can't we assume that most people want to set up a private server if they go through this document?

I don't think we should limit the manual to set up a private server. In my case, I wanted a public server so that my server is used for more than a few hours each week. Sharing a server allows for other new users to try Jamulus without dealing with server issues.

Would that be a bad idea?

Not at all. macOS is probably as good as Linux. I assume Windows would be more tricky.

I don't think we should limit the manual to set up a private server. In my case, I wanted a public server so that my server is used for more than a few hours each week. Sharing a server allows for other new users to try Jamulus without dealing with server issues.

Hmm. But we could at least focus on setting up a private server (since we already have multiple free public ones around the world. OFC. Some regions might need more servers)

From a first glance, the new server manual looks massive (and complicated). Do we really need that much theory there.

That's sort of the point. If you want to run a server, you need to understand what's involved.

Can't we assume that most people want to set up a private server if they go through this document?

This isn't a "quick setup" guide, it's supposed to contain all the information needed to run as server (and there's nothing new here). So I don't think we should assume anything, any more than we do in the User Manual.

Bandwidth use

That's a duplicate of content above

You mean they overlap? I guess so, in which case we can just have a line at the start that refers to bandwidth use being a function of the number of players on the server, and then just refer to the later detail.

/wiki/Server-Linux That's a guide I personally would have preferred to see right away.

Me too. But that's because I already know about the difference between server types, whether they can be run headless, on what platforms, why, what the impact on bandwidth is etc. etc.

We could turn it upside down: have installation at the start, and then put all the "background knowledge" at the end I guess. But that just feels a bit unsafe in terms of putting people in a good position to understand what they're doing. This isn't like the client side of the docs where we're trying to lower barriers.

Hmm. But we could at least focus on setting up a private server (since we already have multiple free public ones around the world. OFC. Some regions might need more servers)

The public servers are not evenly distributed. around the world. There may be a number of private servers near me and they might as well not exist. I have struggled to learn how to install and run a server because there are not enough (actually, there were no) public servers near me. This documentation is needed to lower the barrier to install and maintain servers.

Can't we assume that most people want to set up a private server if they go through this document?

In my experience, most of the people new to Jaumulus want to set up a server because a nearby public server does not exist or because they are not sure they are welcome to use a nearby server. A good percentage of these interested users never succeed in getting all the elements working.

This isn't like the client side of the docs where we're trying to lower barriers.

Except it is very important to make it easy to succeed with installing a server. A new user cannot succeed without a server.

Except it is very important to make it easy to succeed with installing a server. A new user cannot succeed without a server.

Yes. But none of the information on installation is new in this PR, I'm just re-arranging it so that it's easier for us to maintain (for reasons that may not be very easy to explain, I admit!).

Or is that not what you mean?

But we could at least focus on setting up a private server (since we already have multiple free public ones around the world. OFC. Some regions might need more servers)

What do you think if we put the following in the Server Types section?

"Note: Please do not set up a Public Server if you can see servers in your connection list that have ping times of less than 20ms. Doing so may prevent others from registering servers in locations that need them."

so that it's easier for us to maintain (for reasons that may not be very easy to explain, I admit!).
Or is that not what you mean?

I admit documentation for newbies is difficult to write. I was referring back to a comment that the newbie musician only needs to know how to install a client (which a lot of effort has been made to make it easy... thank you). Some newbies also needs to know how to install a server. The challenge is that lot of knowledge is second nature for our development community. This assumed knowledge makes it difficult for non-developers or non-sysadmins.

The only way I know to address this is to follow the documentation literally step-by-step. The doc is complete when it is possible to be successful with strictly following the step-by-step. We can't document the world so there will be places that needs to say <at this step, you need to know/read about xxx at yyy. Pay special attention to options zzz>. I am trying to find enough free time to review the doc in process from this perspective.

@gene96817

I am trying to find enough free time to review the doc in process from this perspective.

Just to be clear though, that isn't the purpose of this PR, which is to collect existing information into a more maintainable form, and to make a counterpart of the User Manual where people can easily find information.

I would say too that adequately to cover all the issues needed for a complete novice to install and configure a server (let alone Linux cloud) may produce substantially more documentation compared to current because systems (particularly Linux, but also others) can have substantial differences which make detailed instructions "brittle". This then requires the user to know which alternatives to follow in their particular case. The writer won't be able to predict all of the variations, so frequent updates and expansions will need to be made, at least at first. That's been the history of the documentation for Jamulus so far. But keeping such documentation translated and updated over time is a big challenge for us.

I would say that if you want to follow a "novice guide" to server installation, there are already a few such documents out there I think.

Merging as we can still move all the stuff around before a new release. Thanks!

I would say that if you want to follow a "novice guide" to server installation, there are already a few such documents out there I think.

So far, all the novice guides are insufficient. They don't give any clues about the assumptions or why. Then when a glitch happens (even a minor one) only an experienced human can help. (You could say the assumptions are the system variables and prerequisites that should be installed.)

Several of the novice guides worked for me once. Then when I need to go back to reinstall, the proscribed process fails. If it was a sandbox system solely to run Jamulus, then rebuilding everything from scratch is an option. If the system is also running other useful things, it is hard to flush everything to have a clean initial system for Jamulus.

I'm ok with being the dunce testing out the documentation for hidden assumptions.