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

Merged
merged 5 commits into from
Mar 29, 2019
Merged

Add comprehensive installation instructions #206

merged 5 commits into from
Mar 29, 2019

Conversation

RulerOf
Copy link
Contributor

@RulerOf 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.

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
Copy link
Owner

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
Copy link
Contributor 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
Copy link
Owner

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.

@phreaker0 phreaker0 added the revision needed Changes are required for this PR to be merged label Dec 7, 2018
@backamblock
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
Copy link
Contributor 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
Copy link
Collaborator

@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
Copy link
Owner

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 phreaker0 assigned jimsalterjrs and unassigned RulerOf Feb 20, 2019
@phreaker0 phreaker0 added ready to merge and removed revision needed Changes are required for this PR to be merged labels Feb 20, 2019
@phreaker0
Copy link
Collaborator

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

Copy link
Contributor

@danielewood danielewood left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Fixed systemd paths to match install location.

[Service]
Environment=TZ=UTC
Type=oneshot
ExecStart=/usr/sbin/sanoid --take-snapshots
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
ExecStart=/usr/sbin/sanoid --take-snapshots
ExecStart=/usr/local/sbin/sanoid --take-snapshots

[Service]
Environment=TZ=UTC
Type=oneshot
ExecStart=/usr/sbin/sanoid --prune-snapshots
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
ExecStart=/usr/sbin/sanoid --prune-snapshots
ExecStart=/usr/local/sbin/sanoid --prune-snapshots

@jimsalterjrs jimsalterjrs merged commit 4783470 into jimsalterjrs:master Mar 29, 2019
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Development

Successfully merging this pull request may close these issues.

5 participants