kemonine
/
lollipopcloud
Archived
1
0
Fork 0
Code Releases Activity

added how-to-gitea for beginners and the forgetful (#9) 

Merge how-to-gitea docs from @jmf
This commit is contained in:
jmf 2018-06-18 17:29:43 +00:00 committed by Gitea
parent 7aa1966290
commit f132454967
2 changed files with 151 additions and 15 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

63
README.md
View File

@ -1,49 +1,82 @@
# Introduction
The Lollipop is a [single-board computer (SBC)](https://en.wikipedia.org/wiki/Single-board_computer) cloud device, with the ability to manage your own cellular internet, wifi, VPN, firewall, web server, data backup and syncing, ad blocker, notes and project management, git, RSS feeds, "read it later" bookmark management, GPS mapping, and more. Some of these features (like GPS and cellular internet) require extra hardware, but the base device consists of an SBC with an SD memory card loaded with Armbian.
The Lollipop is a [single-board computer (SBC) (link)](https://en.wikipedia.org/wiki/Single-board_computer) cloud device, with the ability to manage your own cellular internet, wifi, VPN, firewall, web server, data backup and syncing, ad blocker, notes and project management, git, RSS feeds, "read it later" bookmark management, GPS mapping, and more. Some of these features (like GPS and cellular internet) require extra hardware, but the base device consists of an SBC with an SD memory card loaded with Armbian.
# Getting Started
You will need a single-board computer (SBC) like a [Pine64](https://www.pine64.org/) or an [Orange Pi](http://www.orangepi.org/). For more about hardware, and why the Raspberry Pi is not recommended, see the [hardware notes](https://git.lollipop.holdmybeer.solutions/lollipop-cloud/lolipop_lan_cloud/src/branch/master/docs/hardware_notes.md).
You will need a single-board computer (SBC) like a [Pine64](https://www.pine64.org/) or an [Orange Pi (link)](http://www.orangepi.org/). For more about hardware, and why the Raspberry Pi is not recommended, see the [hardware notes (link)](https://git.lollipop.holdmybeer.solutions/lollipop-cloud/lolipop_lan_cloud/src/branch/master/docs/hardware_notes.md). There are more [preflight hardware considerations (link)]([I'm a relative reference to a repository file](../blob/master/LICENSE)), as well.
For the basic start up and set up of your Pine64, you will need either (a) a keyboard and a way to view the display (HDMI cord OR a [serial console](https://www.pine64.org/?product=padi-serial-console)), OR (b) an ethernet connection.
You will also need an SD card formatted with Armbian installed.
## Installing Armbian onto an SD card
[Armbian](https://www.armbian.com/) is a Linux operating system based on Debian and Ubuntu, specifically designed for [ARM boards](https://en.wikipedia.org/wiki/ARM_architecture). You will need to [download Armbian for the board you're setting up](https://www.armbian.com/download/) (we're using a Pine64 and recommend [Armbian Xenial](https://www.armbian.com/pine64/)), and save it to your computer. NOTE: experienced users might want to use the experimental versions, but the rest of us should stick to the supported and stable builds.
[Armbian](https://www.armbian.com/) is a Linux operating system based on Debian and Ubuntu, specifically designed for [ARM boards (link)](https://en.wikipedia.org/wiki/ARM_architecture). You will need to [download Armbian for the board you're setting up (link)](https://www.armbian.com/download/) (we're using a Pine64 and recommend [Armbian Xenial (link)](https://www.armbian.com/pine64/)), and save it to your computer. NOTE: experienced users might want to use the experimental versions, but the rest of us should stick to the supported and stable builds.
You will need to extract (unzip) the Armbian file once it downloads. Armbian is downloaded as a 7z archive (with the file extension .7z), so you may need a special program to extract this file. Try [Keka](https://www.keka.io/) for MacOS, [7-zip](http://www.7-zip.org/) for Windows, or 7z for Linux (`apt-get install p7zip-full`). Extract the file to a location you can remember (such as your desktop).
You will need to extract (unzip) the Armbian file once it downloads. Armbian is downloaded as a 7z archive (with the file extension .7z), so you may need a special program to extract this file. Try [Keka (link)](https://www.keka.io/) for MacOS, [7-zip (link)](http://www.7-zip.org/) for Windows, or 7z for Linux (`apt-get install p7zip-full`). Extract the file to a location you can remember (such as your desktop).
You will need to format your SD card as FAT32 before you can use it.
You will need to format your SD card as FAT32 before you can use it.
To format an SD card on a Mac, open Terminal and use this command: `diskutil eraseVolume FAT32 ARMBIAN /dev/usb1` where ARMBIAN is the permanent name of your drive (so change it if you wish) and /dev/usb1 is the location of your SD card. The easiest way to find the location of your SD card is to open Finder, click on your computer's name under devices, and you should see your SD card in the list. Right-click (or `command + click`) on that SD card, and choose "copy." When you paste (`command + V`) into Terminal, it will paste the path of the device (such as `/Volumes/UNNAMED`). After you run `diskutil eraseVolume FAT32 ARMBIAN /dev/usb1`, it's time to install Armbian.
Windows users will need some separate instructions. For now, try [Wikihow's article about formatting with Windows](https://www.wikihow.com/Format-FAT32).
Windows users will need some separate instructions. For now, try [Wikihow's article about formatting with Windows (link)](https://www.wikihow.com/Format-FAT32).
If you don't already have one, you will also need an application/program to properly prepare your formatted SD card. [Etcher](https://etcher.io/) works on most computers. To use Etcher: Insert the SD card into your computer (using an built-in reader or an external USB reader), load Etcher, select your newly extracted Armbian .img file, select the SD card you want to set up, and click Flash!
If you don't already have one, you will also need an application/program to properly prepare your formatted SD card. [Etcher (link)](https://etcher.io/) works on most computers. To use Etcher: Insert the SD card into your computer (using an built-in reader or an external USB reader), load Etcher, select your newly extracted Armbian .img file, select the SD card you want to set up, and click Flash!
When Etcher is finished, you're ready to insert your Armbian SD card into your Pine64. Insert your HDMI cable or serial console, and keyboard or ethernet if you are using it, and then plug in the power cord. The Pine64 should boot automatically.
If your board does not boot (the screen is blank or you cannot connect via SSH), but the power light is on and your SD card is properly inserted into the Pine64 (make sure it clicks into place!) your SD card may not have flashed properly. Repeat the process for formatting the SD card and running Etcher, and try again.
If your board does not boot (the screen is blank or you cannot connect via SSH), but the power light is on and your SD card is properly inserted into the Pine64 (make sure it clicks into place!) your SD card may not have flashed properly. Repeat the process for formatting the SD card and running Etcher, and try again.
## Your First Time Booting Armbian
If you're not using a keyboard, connect your Pine64 with an ethernet cable to your local router and use your development computer to load Terminal (if using a Mac) and run `ssh root@192.168.1.x` (your board's IP address! make sure to use the root@IP_address format or else Terminal will tell the Pine64 that you're trying to log in with your Mac's username) OR use [PuTTY](https://putty.org/) to open an SSH connection to your Pine64. You may need to log into your router's settings to [find the IP address of your Pine64](https://www.howtogeek.com/204057/how-to-see-who%E2%80%99s-connected-to-your-wi-fi-network/).
If you're not using a keyboard, connect your Pine64 with an ethernet cable to your local router and use your development computer to load Terminal (if using a Mac) and run `ssh root@192.168.1.x` (your board's IP address! make sure to use the root@IP_address format or else Terminal will tell the Pine64 that you're trying to log in with your Mac's username) OR use [PuTTY (link)](https://putty.org/) to open an SSH connection to your Pine64. You may need to log into your router's settings to [find the IP address of your Pine64 (link)](https://www.howtogeek.com/204057/how-to-see-who%E2%80%99s-connected-to-your-wi-fi-network/).
Both keyboard and ethernet users will continue on the same path here:
![First login screen](/screenshots/first-login.png)
At first boot, you will be prompted to log in with the default login (root) and password (1234), and then prompted to change your root password. When you set your root password, make it a good one and don't forget it! Anyone with root access to your computer will have access to everything on that computer, including the ability to make malicious changes.
At first boot, you will be prompted to log in with the default login (root) and password (1234), and then prompted to change your root password. When you set your root password, make it a good one and don't forget it! Anyone with root access to your computer will have access to everything on that computer, including the ability to make malicious changes.
Next, you will be prompted to create a new user account and password. This account will have [sudo](https://en.wikipedia.org/wiki/Sudo) privileges, which is just as powerful (and dangerous) as root access, so you'll need another secure password. It is good practice to never login as root, so you'll be using this new user account for everything going forward.
Next, you will be prompted to create a new user account and password. This account will have [sudo (link)](https://en.wikipedia.org/wiki/Sudo) privileges, which is just as powerful (and dangerous) as root access, so you'll need another secure password. It is good practice to never login as root, so you'll be using this new user account for everything going forward.
Once you've created an account, the desktop environment will load, and it's time to start setting things up!
NOTE: If you are connected via SSH (running without a display or "headless"), you can also install [VNC Viewer](https://www.realvnc.com/) on your development computer, and [set up VNC (Virtual Network Computing) on your Pine64](https://forum.pine64.org/showthread.php?tid=794), so you can connect virtually without having to deal with a separate keyboard/monitor/etc setup. This is something you may use many times in the future, so it's worth taking the time to set it up, even if you're currently using a dedicated keyboard and display for your Lollipop. [More information about VNC.](https://en.wikipedia.org/wiki/Virtual_Network_Computing)
NOTE: If you are connected via SSH (running without a display or "headless"), you can also install [VNC Viewer (link)](https://www.realvnc.com/) on your development computer, and [set up VNC (Virtual Network Computing) on your Pine64 (link)](https://forum.pine64.org/showthread.php?tid=794), so you can connect virtually without having to deal with a separate keyboard/monitor/etc setup. This is something you may use many times in the future, so it's worth taking the time to set it up, even if you're currently using a dedicated keyboard and display for your Lollipop. [More information about VNC. (link)](https://en.wikipedia.org/wiki/Virtual_Network_Computing)
![The view with VNC Viewer](/screenshots/vnc-viewer.png)
## Base Setup
It's good practice to run `sudo apt-get update` at the command line to make sure everything is up to date.
# Base Setup
(to be continued...)
At this point, you might be ready to jump into the [Lollipop base setup code (link)](https://git.lollipop.holdmybeer.solutions/lollipop-cloud/lolipop_lan_cloud/src/branch/master/docs/armbian/base_setup.md). If you need a little more detail, continue following along here instead.
If you are sticking with the command line via SSH, these steps will hopefully be straightforward. If you are using your new Lollipop with the desktop environment, you will have to open up a terminal window.
It's good practice to run `sudo apt update` at the command line to make sure everything is up to date, and you may need to run `sudo apt upgrade` as well (the command line will tell you if there are upgrades but it won't hurt to run it either way). After updating and upgrading, run `systemctl reboot`, give the board a minute or two to reboot, and then reconnect via SSH.
__Note:__ if you get an error like `perl: warning: Falling back to a fallback locale ("en_US.UTF-8").
locale: Cannot set LC_CTYPE to default locale: No such file or directory
locale: Cannot set LC_ALL to default locale: No such file or directory`, try the following command: `export LC_ALL="en_US.UTF-8"`.
You will have to edit some files. Nano is a simple built-in text editor, but feel free to use your text editor of choice. Examples here will use Nano.
You will be disabling auto-updates in order to save bandwidth and time, and to prevent data overages for those with data caps.
First file to edit:
`sudo nano /etc/apt/apt.conf.d/02periodic`
and change the line ```APT::Periodic::Enable "1";``` to ```APT::Periodic::Enable "0";```
Then enter command `control-x` (to exit) and choose `y` to save changes. Hit enter to keep the file name the same, and now you're reading to move on to the next file.
Second file to edit: `sudo nano /etc/apt/apt.conf.d/20auto-upgrades` and change the line ```APT::Periodic::Update-Package-Lists "1";``` to ```APT::Periodic::Update-Package-Lists "0";```
AND change ```APT::Periodic::Unattended-Upgrade "1";``` to ```APT::Periodic::Unattended-Upgrade "0";```
(remember to `ctrl-x` and `y` to save your changes).
Third file to edit: `sudo nano /etc/ssh/sshd_config` and make sure the following is set: `PermitRootLogin no`. This is a longer file, so enter `ctrl-w` to search for `PermitRootLogin`. You may have to `ctrl-w` and `enter` again to find the line you're looking for. Change `yes` to `no` if necessary and then save your changes (`ctrl-x` and `y`).
Now restart the service with `systemctl restart sshd`.
## Congratulations! You've installed an entire operating system and completed the base setup! Time to customize your Lollipop!
For now, you can try the dev-level documentation for the [Lollipop project (link)](https://git.lollipop.holdmybeer.solutions/lollipop-cloud/lolipop_lan_cloud) (you have completely finished The Basics section, and you are ready to dive into Networking), but beginner-level documentation is in the works and this will be updated as it is completed.
Check and contribute to (the issue tracker (link))[https://git.lollipop.holdmybeer.solutions/lollipop-cloud/docs/issues] for errors, typos, questions, and omissions to help improve this documentation. Thanks!

103
how-to-gitea.md Normal file
View File

@ -0,0 +1,103 @@
# Gitea cheat sheet for beginners and the forgetful
Below is the basic Gitea workflow, to help you with your contributions. But do not hesitate to reach out to any of the organizers for help! We're happy to walk you through any or all of this, no matter what your experience level. If you've never even heard of Gitea before, we'd love to help you submit your first contribution!
This document gets wordy because Git is not as welcoming to beginners as we wish it was, but you can do it! And you're not alone! We are just a message or comment away. There are even more resources in the [Bibliography](#Bibliography) at the end, if you want to dive deeper. You may even want to skip this document entirely at first, and try [Your First Pull Request (link)](https://joshuahunter.com/posts/your-first-pull-request/) more suited to your needs.
If you just can't get enough Git (perhaps because you are a glutton for punishment), check out the [Git Book (link)](https://git-scm.com/book/en/v2).
# Basic Steps For Contributing
These are the general steps, but if you need more information, keep reading.
* Fork the repository (just once!) from [Lollipop Cloud project page (link)](https://git.lollipop.holdmybeer.solutions/)
* Clone your fork on your own computer
* Edit, make changes and contributions
* Push those changes to your fork
* Open a merge/pull request in Gitea
* Wait for project coordinator to provide feedback or approve the merge/pull request
# And now... what to do if you've never done this before
### Log in to Gitea
If you haven't already, create an account on the [Lollipop Cloud project page (link)](https://git.lollipop.holdmybeer.solutions/) and log in.
### Fork it! (copy the project to your Gitea account)
View the repository you would like to work on (code, docs, website), and click `Fork` in the upper right corner. You will only have to fork once!
A fork is an exact copy of the project as it existed at the exact moment you forked it. So when the project updates in the future, you will have to update your code too, but we will talk about that later.
At this point, you will need a command line client like [PuTTY (link)](https://putty.org/) for Windows users, or the built-in Terminal for MacOS users.
### Create a directory (an empty folder) for where you'd like your copy of the project to live, and open it.
In PuTTY or Terminal, enter each of the following commands, where "lollipop_project" is the name of directory where you would like to store the clone.
`mkdir /path/to/lollipop_project`
`cd /path/to/lollipop_project`
### CLONE (create a local copy) of the project files
View your newly created fork in your web browser and copy the https:// address in the box on the right side of the page.
In your terminal program, enter `git clone https://git.lollipop.holdmybeer.solutions/your-username/forked-repository`, with the correct URL.
You are downloading all the project files to your computer! Yay!
### View your cloned project on your computer
Git will install the project in a new folder. Use the command `ls` to see the name of the new project folder if you are unsure. Open this new folder with
`cd cloned_directory_name` to see what was installed.
### Edit your contributions!
Now that the files live locally on your computer, you can edit them with your favorite editor. Stick with the command line (Vim, Emacs, Nano), or use a text editor like [Atom (link)](https://atom.io/). Be sure to save your changes!
### Add your changed files to git, to prepare them for uploading
If you added new files to the project, in your terminal you will have to `git add edited-file-name` for each of those new files.
### Commit your changes
When you're ready, go back to the command line and commit your changes with a short but descriptive comment.
`git commit -m "Updated List of Anthropomorphic Potatoes"`
### Push your changes to your fork
When you're really ready, "push" those changes to the original source, which is a request to accept and merge your contributions with the rest of the project. **Note:** A push request and a merge request are the same thing.
`git push origin master`
### Create a pull request (AKA merge request)
Go back to your browser and your forked repository `https://git.lollipop.holdmybeer.solutions/your-username/forked-repository` and go to Pull Requests and choose `New Pull Request`.
There will be two drop-down menus that will probably say `base: master` and `compare: master`. (As you get more advanced, you can create branches to compare. For our purposes, just select the two available branches that are probably named `master`. The "base" fork is the original project, NOT your forked version.) Enter a short title for the changes, a description to help reviewers understand your contributions, and click the big `Submit Pull Request` button below your text.
## Congratulations! You've submitted your first pull request! 🎉
The developers will review your changes and work with you on next steps.
# Troubleshooting
## What to do when "upstream" changes...
"Upstream" is the name of the original code (not your fork). When it gets updated after you clone or fork, you will have to request a copy of those changes to stay up-to-date.
### Add the upstream path (Do this step only once!)
If the master (where you forked FROM) changes, you will have to update your local clone. You will only have to do this step ONE time!
From your `/path/to/lollipop_project/new_clone_directory/` directory,
Do this: `git remote add upstream https://git.project-domain.com/forked_from/original_repository.git` with the original repository URL.
### Fetch the changes since you first forked or last fetched changes
In order to be sure you're working off the latest copy of the project, you can fetch the latest changes with `git fetch upstream`. (Note: this can only be done at the command line, not the user interface/URL.)
Now you have the latest copy of the project in your local directory. Your new changes from this point forward will be stored in a local branch called `upstream/master`.
Make your edits!
### Merge your changes with the upstream repo (the original repo that you forked).
`git merge upstream/master`
# Bibliography
* [Atom text editor (link)](https://atom.io/)
* [Git Book (link)](https://git-scm.com/book/en/v2)
* [Git Cheat Sheet (link)](https://github.com/mikeizbicki/ucr-cs100/blob/2015winter/textbook/cheatsheets/git-cheatsheet.md): May be helpful for setting up Git from scratch.
* [Git Cheat Sheet - Advanced (link)](https://github.com/mikeizbicki/ucr-cs100/tree/2015winter/textbook/tools/git/advanced-git)
* [Git Game (link)](https://www.git-game.com/): get serious about Git by gameifying your learning.
* [Oh shit, git! (link)](http://ohshitgit.com/): how to fix a few Git mistakes (we all make them!)
* [PuTTY SSH and telnet client (link)](https://putty.org/)
* [Syncing a fork (link)](https://help.github.com/articles/syncing-a-fork/)
* [Your First Pull Request (link)](https://joshuahunter.com/posts/your-first-pull-request/)