Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add comprehensive installation instructions #206

Open
wants to merge 5 commits into
base: master
from

Conversation

Projects
None yet
4 participants
@RulerOf
Copy link

RulerOf commented Mar 26, 2018

Converts the old INSTALL file to a markdown-formatted INSTALL.md file
that contains comprehensive installation instructions for supported
operating systems, and an outline that can be used on others where
Sanoid/Syncoid ought to work.

The Installation section is complete for CentOS/RHEL, and has been
"dressed up" for FreeBSD/Ubuntu. Those ones still need to be completed.
I don't cover the topic of running Syncoid periodically or how to do it
because I don't know. It's probably out of scope for the Installation
guide anyway.

The Configuration sections is intended to walk through some common
setups for sanoid.conf. I suggest just cleaning up the existing conf
file examples and putting them into that section.

Fixes #192


This is a followup on this Reddit discussion from a few days ago. Let me know if there's anything that should be changed or otherwise cleaned up.

RulerOf added some commits Mar 26, 2018

Add comprehensive installation instructions
Converts the old INSTALL file to a markdown-formatted INSTALL.md file
that contains comprehensive installation instructions for supported
operating systems, and an outline that can be used on others where
Sanoid/Syncoid ought to work.

The Installation section is complete for CentOS/RHEL, and has been
"dressed up" for FreeBSD/Ubuntu. Those ones still need to be completed.
I don't cover the topic of running Syncoid periodically or how to do it
because I don't know. It's probably out of scope for the Installation
guide anyway.

The Configuration sections is intended to walk through some common
setups for sanoid.conf. I suggest just cleaning up the existing conf
file examples and putting them into that section.
@jimsalterjrs

This comment has been minimized.

Copy link
Owner

jimsalterjrs commented Jun 28, 2018

So, I like the work you did here, but I'm a little wishy-washy about taking it. Markdown is pretty on Github, but it's more of a PITA to parse on the command line, and I'm partial to the idea of being able to read the install docs with a simple less when you're actually on the console and working.

Thoughts?

@RulerOf

This comment has been minimized.

Copy link
Author

RulerOf commented Jun 28, 2018

I would say that Markdown is appropriate for installation instructions because they include acquiring the software—something that you don't typically read up on in the terminal.

Aside from that, I do think it's generally appropriate for software to have markdown-formatted documentation for ease of reading when viewing things online, where less-pretty documentation and examples is for --help invocation and man pages. Code blocks in particular are critical pieces of software documentation that allows people "get up and running fast."

This format is a good choice for making the software more accessible to the novice or enthusiast without seriously hampering or inconveniencing experienced professionals.

If you like/accept this PR, I would add a link to this document from the main readme, and submit another PR for that if you like. Consider opening an issue to see if anyone has suggestions for the configuration section of this document, or if that should be split into another file and documented there—it's very related but just out of scope for what I was working on.

@jimsalterjrs

This comment has been minimized.

Copy link
Owner

jimsalterjrs commented Jun 28, 2018

I'm definitely okay with this as a separate document designed/intended to be read on Github and linked to from the main readme..

There is the issue of then needing potentially to maintain two different sets of instructions, but then again, it gives us the chance to take some baby steps and perhaps in the future look at who's using which more frequently.

@backamblock

This comment has been minimized.

Copy link

backamblock commented Jan 18, 2019

i would really like to use sanoid and syncoid but i am having a hard time installing and configuring it, can you please update this instruction and include it in /master?

@RulerOf

This comment has been minimized.

Copy link
Author

RulerOf commented Jan 25, 2019

@backamblock When I originally wrote this, I had to leave some parts either blank or unfilled because I didn't have enough information to finish it properly at the time, and had sort of hoped someone else might step in.

I'll carve out some time to spend an hour or two on it either this weekend or next, and will add the instructions necessary for use on Ubuntu/Debian as well.

@phreaker0 if you want to add me as a reviewer, I'll tag this PR with my review once I update it.

@phreaker0

This comment has been minimized.

Copy link
Collaborator

phreaker0 commented Feb 19, 2019

@jimsalterjrs are you still objected to markdown? I would also like to have a single install instruction file, if you are against markdown I would suggest to adapt the plaintext install instruction with the information in this PR (thx @RulerOf)

@jimsalterjrs

This comment has been minimized.

Copy link
Owner

jimsalterjrs commented Feb 19, 2019

Eh, I'm OK with markdown. Honestly it's all sort of baby steps that will/should eventually not matter anyway; one of these days we really need to just have real packages available for the majority distros.

phreaker0 added some commits Feb 20, 2019

@phreaker0

This comment has been minimized.

Copy link
Collaborator

phreaker0 commented Feb 20, 2019

@jimsalterjrs @RulerOf I rebased the branch and added recent changes

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
You can’t perform that action at this time.
You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session.