DEV Community: PhoenixLandPirate

Bridging using Matrix with Ansible. (WIP)

PhoenixLandPirate — Fri, 04 Dec 2020 19:53:03 +0000

Bridging and why?

What is a Bridge? well as the name suggests, its a link between one place and another, in this case, its linking messaging platforms of different kinds, to one messaging platform.

Why do this? theres a few reasons why.

One place, if you bridge your chats, then everyone who messages you will be in one place, you only have to open one app, to get all your messages, you might not want this for everyone everywhere, some accounts you want to keep seperate, but for those chats who you wish where just on one app, its easy, when you get a new phone, or computer, you just have to login to one app, you dont need to download loads of apps.

Storage space and battery life, applications take up storage space, they all have there little jobs running in the background, each waking up your phone, or taking a bit of energy, slowing your phone down, or wasting battery life, and data.

Avoid using dodgy apps, Facebook apps, are known for their obtrusive nature, how they send weird data, if you want to talk to your friends on facebook, but you want control over your data, you can't do it without bridges.

Freedom of movement, many messaging apps limit where you can use them, some apps only work on desktop, others only on phone, some don't work on windows phone, Ubuntu Touch, sailfish, etc, with a matrix bridge, anything that can connect to a matrix client will let you read your messages, you don't have to be on your phone, to message your whatsapp friends, you can message your facebook friends on Plasma mobile.

The Set Up.

I started with creating a Linode server, 1gb of ram with 25 GB of storage, on CentOS7 (CentoOS 8 is not supported by the playbook we are using) depending on how many messages you want to send on the services, you may need a much bigger server, I plan on keeping an eye on how much the server uses, and upgrade it when/if I need to, if I only get a handful of messages through a bridge, that just use standard text then a low end server should be fine.

CentOS7 uses yum, so using yum we will update and restart the server

$ sudo yum update
$ reboot

From there I will be following this readme https://github.com/spantaleev/matrix-docker-ansible-deploy/blob/master/docs/README.md

On centOS 7, or at least the version on Linode, python and cronie are already installed, so we can bypass installing them
I already have a server running ansible, so I can just ssh into that machine.

Then we need to buy a dns, I bought a cheap one from namecheap, this doesn't need to be anything easy to remember, as no one is going to use this except you, it doesn't have to be a .com or anything to recognizable, so I went with the cheapest, using a .xyz

NameCheap to Linode

This is how I set up NameCheap DNS with Linode, however if you're using different services, you may want to read there documentation.

Go to your dashboard, then click manage on the DNS page, go to the NAMESERVERS secotion, and use a Custom DNS, and add the linode server's

ns1.linode.com
ns2.linode.com
ns3.linode.com
ns4.linode.com
ns5.linode.com

Then click the green tick, you may need to be pacient because it can take up to 24 hours to make the Name servers change.

Go to your linode cloud service, then click Domains, and make the Master domain, the Domain is the url you bought, and the SOA Email address is just the accountable, so in short, your email, if you get an error saying that the domain isn't valid, you might just have your finger on the button to quickly.

Now its time to set up your DNS.

Type	Host	Priority	Weight	Port	Target
A	matrix	-	-	-	matrix-server-IP
CNAME	element				matrix.
CNAME	dimension (*)				matrix.
CNAME	jitsi (*)				matrix.
SRV	_matrix-identity._tcp	10	0	443	matrix.

The ones marked with >(*) are optional, and since we are only using this as a bridge server, we will not be setting them up.

To add the A type, just click add an A/AAAA Record, make the Hostname matrix, and the matrix-server-IP, is just the IP address of the server.
Do similarly with the CNAME and SRV's.

This is roughly what your set up should look like if you're not using some of the extra features offered in the playbook!

Playbook

Now its time to configure the Ansible and the playbook.

so lets ssh into the Ansible server.

first I had to install git as it didn't git preinstalled

$ sudo yum install git
$ sudo yum install python-dns
$ git clone https://github.com/spantaleev/matrix-docker-ansible-deploy.git

cd into the new folder and set up with some simple commands.

$ cd matrix-docker-ansible-deploy
$ mkdir inventory/host_vars/matrix.
$ cp examples/host-vars.yml inventory/host_vars/matrix./vars.yml
$ nano inventory/host_vars/matrix./vars.yml

in this file you just add your websites URL, your email address and add two secrets.
however, you can also set up some bots quite easily here to get a list of all the options use

$ ls roles

for this set up we're going to use the instagram, facebook and some other services.
So first you'll want to see what the defaults are using

$ less roles//defaults/main.yml

At the start I'm just running them as default as possible, editing them if I need to change a config option, to do that we edit our var file

$ nano inventory/host_vars/matrix./vars.yml

We also need to configure the hosts file, this just points the Ansible playbook, to the server we want to change.

$ cp examples/hosts inventory/hosts
$ nano inventory/hosts

Also to make this a bit easier, it might be a good idea to generate a ssh key so generate a ssh using ssh-keygen,

$ ssh-keygen
$ cat $HOME/.ssh/id_rsa.pub

Then copy that output to your other servers authorized keys
nano .ssh/authorized_keys

once that's done, go back to our ansible server and run

$ ansible-playbook -i inventory/hosts setup.yml --tags=setup-all

Mine still didn't work, so I had to open a few ports.

$ firewall-cmd --zone=public --add-port= --permanent
$ firewall-cmd --reload

After getting kicked out of the facebook room and told that I don't have permission to use my bots, I asked how to fix my issue, turns out in the var.yml you have to tell the service that you have to whitelist servers which aren't your own.

To fix that, I just added the following to the vars.yml

matrix_mautrix_facebook_configuration_extension_yaml: |
bridge:
permissions:
# Keep the default used by the playbook, referencing the current domain
' matrix_mautrix_facebook_homeserver_domain ': user
another-server.com: user

matrix_mx_puppet_instagram_provisioning_whitelist:

"@.*: matrix_domain|regex_escape "

"@.*:another-domain.com"

matrix_mx_puppet_discord_provisioning_whitelist:

"@.domain.com"

This is roughly how it should look depending on how you plan to organzise your vars.yml page, with your personal data in.

then run the following commands to update the matrix server.

$ ansible-playbook -i inventory/hosts setup.yml --tags=setup-all
$ ansible-playbook -i inventory/hosts setup.yml --tags=start

This fixed Instagram and Discord bridging, however Facebook refused to work, for now I've decided to ssh into the server which hosts my matrix bridges directly, this is a bad idea, as its extra leg work, and something that's easy to forget when updating your Ansible config file.

$ nano /matrix/mautrix-facebook/config/config.yaml

scroll down to bridge, in that subgroup, near the bottom, you'll see permissions, this will have your url: user, just change that to be the domain you wish to use, with : user, for example/

permissions
matrix.org: user

This allows anyone with a matrix.org account to message your Facebook bot, and use it as a bridge, if you don't want that you can configure it to be more strict by specifying the user.

when you've configured this, you then go back to your Ansible server and run.

$ ansible-playbook -i inventory/hosts setup.yml --tags=start

However remember that every time that you run ansible-playbook with the tags "setup-all" you'll have to ssh into your matrix server to change the Facebook config file.

Setting up and Logging in.

Now its just a matter of logging in, to login you have to start a chat with the bot, and usually give login details, however sometimes its a bit more complicated.

Instagram

@_instagrampuppet_bot:DOMAIN.COM

for Instagram, I just plain logged into this one, it even works with 2FA, to login just type

link $USERNAME $PASSWORD

Wait for it to ask you for your 2fa code then just type that, and you're in.

Discord

Before you run the ansible commands, you have to get yourself a discord client ID as well as a Client Secret, but how do you do that?

First go to the developer website then create a new application, create app, then find the create bot button, and click that, "Yes Do it".

Now you'll be on a page that shows you the Client ID, copy and paste that to the vars.yaml in between the quote marks here.

matrix_mx_puppet_discord_client_id: "CLIENT ID"

Next to that will be the client secret, click copy and then paste it to the vars.yml, in between the quote marks here.

matrix_mx_puppet_discord_client_secret: "SECRET ID"

Now use the Ansible commands to setup and start the services.

join the room @_discordpuppet_bot:DOMAIN.COM

Now we can't login by using our username/email, or password, we actually have to use an ID.

Press CTRL+SHIFT+I in the discordapp, and then click on the network tab on the client, press f5 to reload, so that the page can store the information needed.

In the search box, type /api, and click applications, then in headers, search for the autherzation title, copy the code in there.

Then to login just use

link user AUTHCODE

and you'll be in, though be warned its against the discord terms and services to use the Auth code like this.

Facebook

Facebook isn't as difficult as discord, however it's not as simple as instagram either.

first start a chat with the facebook bot @facebookbot:DOMAIN.COM

message the bot with

login-cookie

and follow the instructions from there, make sure you use messanger.com, and dont go to facebook.com and open messanger in full screen, if you use facebook.com/messanger then you'll get a failed login!

Backing up securely with Restic

PhoenixLandPirate — Thu, 26 Nov 2020 14:14:48 +0000

Backing up securely

We all know the saying, you should always back up your stuff, if you don't back it up, there's lots of things that can go wrong, your hard-drive might fail, or might just have some data loss, you might accidently delete the wrong folder, and not realise it until its to late, or maybe you accidently over wrote a newer file, with an older version, maybe someone could have locked you out of your computer, or encrypted your hard-drive, or perhaps you just forget your password.

Todays blog is about Local backup's only, however the tools used in this can be used to back up your things securely online to, the biggest issue with online backups being the cost of service if you have a huge amount of storage to back up.

Install Restic

Restic is the backup software that we're going to use, its Open Source, with strong encryption, versioning, and only transfers what you need to, so you don't use up more space than you need to.

Restic works on Linux, Mac, BSD, and Windows, however if you want to use Restic, you still need to know your way around a shell.

Windows Scoop and PowerShell

To install Restic on Windows, you have to use the Scoop module, and thus you need to be comfortable with PowerShell.

First make sure that the ExecutionPolicy is set to RemoteSigned for the current user, if you don't understand ExecutionPolicy's it just tells PowerShell what level of security, it should be on, for the current user or machine, in this command we're changing the ExecutionPolicy so that it requires that all scripts and configs, that have been gotten remotely (Not on the local machine) must be signed by a trusted publisher, for the Current User, only, this doesn't change the ExecutionPolicy for any other user on the machine.

Set-ExecutionPolicy RemoteSigned -scope CurrentUser

Then we want to use PowerShell to download and install scoop using this command.

Invoke-Expression (New-Object System.Net.WebClient).DownloadString('https://get.scoop.sh')

Then install Restic by using the command

scoop install Restic

you can than use Restic from the PowerShell environment.

Mac

If you use a Mac you can either use homebrew, or MacPorts, since brew is more widely used, it would be of more use in future projects to install homebrew over MacPorts in my opinion, however, you're more than welcome to install software however you like on your own computer.

To Install homebrew use the command

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install.sh)"

Then you can install programs using brew install, to install Restic just use

brew install restic

Now Restic is up and running

Linux and BSD's

Install using your local repositories.

Alternatively

You can download releases from the Restic GitHub release page, and then you can use Restic self-update when there's a newer version.

You can also build Restic from Source.

Local or Online?

Restic supports many different Backup Locations, these include local back ups, online back ups using someone else's cloud infrastructure, or your own remote services.

A local back up is what I'm going to use in this blog, and so for further examples of other services, I suggest looking at the manual or reading someone else's remote back up solution, however, the majority of this blog will be the same regardless, however where you point the commands to and from will be different, there will also be extra account set up to think about that I wont go talk about in this Blog

Local

Local backups are a great option, they're much faster than using the wireless, and wont slowdown any other time sensitive task ran over the network.

Local also means "buy once" it might be a more upfront cost depending on what hard-drive you get, but you only need to pay that once, for online services, you have to pay monthly to keep up and running.

It can be very cheap if you're going to get a spinning disk/s, however the backup will run slowly, this isn't a big problem if you're only backing up a small amount of data, but if you're backing up a lot, then you might want to purchase a more expensive higher speed SSD, however, a slow backup is better than no backup.

You may also want to consider a SSD if you're planning on moving your backup data around, as HDD's are more perceptible to damage from falls, drops, or bangs.

Local also means that your data is there, so if you use an external drive, you can unmount the drive from one computer, and restore the data to a new machine, without using more bandwidth.

However Local means that you can only access the data if you have the storage medium in front of you, if you don't have the storage media, you don't have your data, if you need to get to your data remotely there are ways of doing it, but its a bit more effort, and can open yourself up to security issues, It also means that if you loose your backup device, or if it breaks then you've lost the data on that drive, which might not be to big of a problem if you still have your primary storage device, but if the reason you loose your data is due to a fire, or a electrical surge damages every device hooked into your computer, than you'll loose two drives in one.

Online

Online backups are great as you can use them anywhere, however they can be slow, especially if you live remote, it can be easier to deal with the cost up front if you're subscribing monthly or yearly, however it may cost more in the long run, if you're only backing up a small amount of data then some backup platforms will allow you to use them for free.

However if you're using your own backup machine, say a raspberry pi that you've set up in another location, the price will barely be different from someone who's using a Local copy.

A remote copy that you own will mean you still have to worry about some of the issues that you have to worry about with Local storage, however you don't need to worry about having both storage options breaking at the same time, but you will have to worry about Online issues, such as bandwidth.

With backing up online, a standard backing up procedure you would also have to be concerned with privacy, but due to Restic's encryption, that isn't a issue that we have to worry about.

If you wish to use online services, Restic offers you the following backup options

Provider	Init URL scheme	Price as of writing
SFTP	restic -r sftp:user@host:/srv/restic-repo init	Self Rolled
REST Server	restic -r rest:http://host:8000/	Self Rolled
Minio Server	restic -r s3:http://localhost:9000/restic init	Self Rolled
Wasabi	restic -r s3:https:/// init	$5.99 for 1 TB per month
Backblaze B2	restic -r b2:bucketname:path/to/repo init	$0.005 per GB (Aprox $5 for 1 TB)
Amazon S3	restic -r s3:s3.amazonaws.com/bucket_name init	$0.024 per GB (Aprox $24 per month for 1 TB)
Microsoft Azure Blob Storage	restic -r azure:foo:/ init	$0.01 per GB (Aprox $10 per month for 1 TB)
Google Cloud Storage	restic -r gs:foo:/ init	They have a calculator
rclone services	restic -r rclone:foo:bar init	Depends what service you're using rclone with

Both

If you can afford the option to do Local and Online, than its best to have one copy in the cloud, and one copy on your desk, it allows you to have the best of both worlds, however the issue majortially, as always will be the cost.

Setting up Local Storage (Linux Only)

I bought a Samsung SSD 860 EVO, with 2TB's of storage as my backup device, it means I don't have to worry about issues with spinning disks or affecting my network speeds, my Pictures directory is 184 GB's so that would take a very long time to upload on my current data speed.

However I do plan to add a online storage backup at some point.

Partitioning the Drive

First step is obvious, you must first plug in the external drive, my external drive connector is USB-C and so I decided to take advantage of the extra speed that USB-C offers over USB type 3, and used a USB-C to USB-C plug.

When I plugged in my SSD it didn't mount, which was quite worrying, however, when I opened KDE Partition Manager, it showed up without a Partition table, this maybe that the Drive didn't come with a partition table on it by default, or more likely, the partition table it came with, just isn't supported on Linux, which one however, we may never know.

So the first thing to do is format the disk, just click on the drive, and then click "New Partition Table" choose GPT, and create the new partition table, however, before we actually create the new partition table, theirs no point in doing that, if we don't add an actual partition, CTRL+N or click "New" will swing open a new popup window in this window, I decided to swap the File system to BTRFS, I didn't enable encryption with LUK's because all the data on the drive will already be encrypted with Restics back up encryption.

I gave it a Label, and then clicked next, typing in my password as it was prompted, and then I mounted the device.

As I'm using KDE Partition manager, I have the problem that I can only write to the device if I'm root, you can check this yourself if you're using Linux and KDE Partition manager, by using ls -l

ls -l /run/media/$USER

This will show you your drives and some information about them, if you see "root root" that means you have to change the owner, but if you see your username instead than that means you'll be okay.

To change the ownership to your current user use chown

sudo chown $USER:$USER /run/media/$USER/backup

Now the device is ready for restic.

Using Restic on a Local drive

First thing to do when starting a new Restic backup is to initiate the repo.

restic init --repo /run/media/$USER/backup

This will then ask you for a new password for the backup, if the data is extremly private, then please do not make a memorable password, but rather use an impossible password, by using a password manager the likes of KeePass or bit-warden, and keep that safe.

Restic will also give you a repository location, mine for example is 2849ef4f60, this is an important number as if you create more repos you'll have to use the repo number to navigate through them.

Now I'm going to back up my Pictures folder, my Pictures folder has all my photos organized into folders, except the Import folder, and some db folder's that I don't need to backup so I create a .exclude.txt file in my Pictures directory, simply saying "import".

restic -r /run/media/$USER/backup backup --tag Photos --verbose=2 ~/Pictures --exclude-file=.exclude.txt

Okay so lets go through this

part of the command	What it means
restic	this starts restic
-r	We are looking for a repository to backup or restore
/run/media/$USER/backup	This is the repository that we're backing up or restoring from
backup	We're backing up some data
--tag Photos	What we're backing up should be tagged, and the tag to this snapshot is Photos
--verbose=2	We are going to display everything we're doing on the commandline
~/Pictures	This is the folder we're backing up
--exclude-file=.exclude.txt	We aren't backing up anything that this document tells us not to

Then that's it, all I need to do now is choose.

Restic Backup options

Lets look through some options that you can use when backing up your files.

Excluding

Exluding command	What you exclude
--exclude=" "	This excludes items with that name, or naming scheme
--iexclude=" "	Same as exclude, but ignores the case of paths
--exclude-caches	Exclude folders containtng a special file
--exclude-file=excludes.txt	Excludes items listed in given file
--iexclude-file=excludes.txt	same as exclude-file execept ignores the case of paths
--exclude-if-present foo	Excludes a folders content if it contains a dffile called foo (optionaly having a given header, no wildcards for hte file name supported)
--exclude-larger-than size	Excludes files larger than the given size

Including
--files-from /tmp/files-to-backup /tmp/aditional-file

Reading from stdin

set -o pipefail
mysqldump [...] | restic -r /srv/restic-repo backup --stdin --stdin-filename production.sql

This pipes the sqldump to a Restic backup, the backup then reads it as standard in using --stdin and we then give that stdin a filename using --stdin-filename.

Working with repositories

You can list a repository by using Restic -r /srv/restic-repo snapshots.

This will give you the ID, Date, Host, Tags, and Directory it backed up from, you can filter these by path using --path=, for example,

restic -r /run/media/$USER/backup snapshots --path="/home/$USER/Pictures"

Will just show you snapshots that are backed up from the pictures directory, you can also filter by user by using '--host &USER', not only can you filter using these tags, you can also list them so that they're specifically grouped by hosts, tags, or directory's, by using --group-by

restic -r /run/media/$USER/backup snapshots --group-by paths

This will group things according to the path that that the backup is from.

It is important to check the integrity of a backup, to make sure that a hard-drive hasn't scrambled any data, or that someone with malicious intent hasn't tried to edit, the file, you can do this by using the check command.

restic -r /run/media/$USER/backup check

If your backup hasn't been tempered with or is still working fine, it will tell you there are no errors and you can continue using the backup, otherwise it's best to restore what you can and create a new backup.

The check command also checks such as none referenced packs in the index, it will often give you some recommendations of what to do with the result of the command, in my case Restic suggests that I have files in the repo which are duplicated, that I can get rid of by using the Restic prune command.

This command can be used to save a lot of hard-drive space

$ restic -r /run/media/*/backup prune
enter password for repository:
repository 2849ef4f opened successfully, password is correct
counting files in repo
building new index for repo
[0:05] 100.00% 16742 / 16742 packs
repository contains 16742 packs (73165 blobs) with 80.012 GiB
processed 73165 blobs: 1989 duplicate blobs, 2.430 GiB duplicate
load all snapshots
find data that is still in use for 2 snapshots
[0:00] 100.00% 2 / 2 snapshots
found 71176 of 73165 data blobs still in use, removing 1989 blobs
will remove 0 invalid files
will delete 0 packs and rewrite 1021 packs, this frees 2.430 GiB

Restoring from a snapshot

Whats the point in having a backup if you don't know how to get the data back off the drive?

One way of restoring from a snapshot is by straight up restoring the data.

First step is to identify which backup you want to restore, by listing your repos, and choosing the ID, for me my id for the latest backup of Photos, is 31e587ea, so to restore my latest backup of that path, I would use the command.

$ restic -r /run/media/*/backup restore 31e587ea --target /Pictures

If you don't want top bother with finding out the ID, you can use tell Restic that you want the latest copy of the Pictures file by using the latest and --path tags.

$ restic -r /run/media/*/backup restore latest --target /Pictures --path "/home/Pictures"

However, perhaps I just want to browse the content of a restic folder, without restoring it, perhaps you only want to restore a handful of files, due to corruption, or are using the backup drive as a portable hard drive.

mkdir /mnt/restic
restic -r /run/media/*/backup mount /mnt/restic

This mounts the Restic backup to a mnt directory, so you can easily browse through it using your favourite file manager.

Automating the backups.

You can automate Restic backups using systemd, using the code as a base bellow, and paste it into our favourite text editor of choice, and save the file to ~/.config/systemd/user/restic-backup.service file. you may have to make some of the folders yourself, and you should edit this to reflect your backup system.

[Unit]
Description=Restic backup service
[Service]
Type=oneshot
ExecStart=restic -r $RESTIC_REPOSITORY backup --verbose --tag Photos $RESTIC_PATHS --password-file="$HOME/Documents/Keys/Backup_Codes/resticpassword"
ExecStart=restic -r $RESTIC_REPOSITORY backup --verbose --tag Documents $RESTIC_PATHS_DOCUMENTS --password-file="$HOME/Documents/Keys/Backup_Codes/resticpassword"
ExecStartPost=restic -r $RESTIC_REPOSITORY forget --verbose --group-by "paths" --keep-within 1y0m0d0h --password-file="$HOME/Documents/Keys/Backup_Codes/resticpassword"
EnvironmentFile=$HOME/.config/restic-backup.conf

These reference an Environment file, which will give the service the needed attributes to run the backup

This is waht my restic-backup.conf looks like

RESTIC_PATHS_PICTURES="$USER/Pictures"
RESTIC_PATHS_DOCUMENTS="$USER/Documents"
RESTIC_REPOSITORY="/run/media/*/Backup"

Last but not least is the timer, if you wish to have a weekly timer, just copy and paste this into a new file, and name it "restic-backup.timer", if youd rather your backups happen hourly, just replace weekly with hourly.

[Unit]
Description=Backup with restic weekly
[Timer]
OnCalendar=weekly
Persistent=true
[Install]
WantedBy=timers.target

Then to kick it of just type

systemctl --user enable --now restic-backup.timer

There you have it that's how you make it so restic automatically backs up your data weekly, using systemd, while also removing year old snapshots, however you still need to prune your data now and again, so you can create another automatic systemd process, or prune it yourself, restic is pretty slow when pruning, so you don't want to do it to often, and you want to make sure that you make a log using the check command to make sure that nothing went wrong during pruning.

Perhaps you've left the timer running for a few days, or have had your computer turned off during the scheduled time, and you want to know where the system is with your backup, you can use systemctl to tell you how long it is until the next time the process will run and when it ran last.

systemctl --user list-timers
NEXT LEFT LAST PASSED UNIT ACTIVATES

Mon 2020-12-07 00:00:00 GMT 5 days left Mon 2020-11-30 00:00:57 GMT 1 day 1h ago restic-backup.timer restic-backup.service

Then you can double check that the backup worked and was successful using the restic check command and restic snapshot command, to make sure that the backup happened and was effective, and to make sure nothing broke, in case something like a shutdown during a backup affected the backup.

Upgrading the PinePhone MainBoard

PhoenixLandPirate — Fri, 20 Nov 2020 22:58:42 +0000

backing up

At the time of writing Ubuntu Touch has many issue around mounting, sharing files, moving files, etc, so its not as simple as just copying and pasting your files from your storage to your SDcard, unless you know your way around the command line.

I decided to back my PinePhone up using the already pre-installed JumpDrive, to enter this, just volume up as you power on the phone, a image of Yumi should appear, saying that its waiting for a command, if you plug in the PinePhone you'll get a big list of mountable drives, we want to mount userdata, than move up into user-data and then phablet.

This gives us a view of all our documents, I selected all the files and straight copied and paste them into a PinePhone sub folder so that I can easily copy and paste them back onto the PinePhone after the upgrade, ultimately this also gives me the ability to properly look the files to remove any old outdated files and just organize my phone a bit more.

Flashing JumpDrive

You'll need a spare SDcard that you don't mind writing over, the new PinePhone mainboard doesn't come with any OS pre-installed, so we have to give the phone a OS to boot off, so that we can flash Ubuntu Touch later!

First download the latest JumpDrive, once that's downloaded, use your favourite flasher, I personally use Etcher, though other people may rather use dd.

After that's flashed you can forget about it until we've installed the mainboard.

Taking apart the PinePhone

Unplug and turn off the PinePhone, take the back cover off, there's a little lip in the bottom right, take the battery out, and remove your SDcard and/or Sim card if you have any installed, this isn't necessary however it means as soon as the mainboard is out, you don't need to worry about it again.

Next is to unscrew the inner frame, this has 15 screws, including a warranty screw, as soon as you remove that screw you have voided your warranty, put the screws to the side, they're all the same size so you don't have to worry about which ones go where, but do keep them safe, because you don't get any extra's, Gently lift up the inner frame, holding onto it from the gap where the battery was, and the outer-side, gently pull it up, holding the rest of the phone down if necessary.

Great you're at the level where you can remove the mainboard, this bit is a bit fidgety, first remove the tags at the bottom of the mainboard gently, these are the easiest to remove, then lift the antenna cable up off the mainboard, there are 3 left to do at this stage, the one on the left, and two on the top, leave the cameras for now, these are easier to remove when the mainboard is out of the case, flip the piece that's keeping the ribbon cables in, and gently remove the cables.

If you didn't use a tool for the last part you'll want one now, the mainboard is kept in place by some tabs, and if you try to remove the mainboard with your nails, you'll most likely hurt yourself, you don't want to use anything metal either as you may damage your mainboard, however, if you have a plastic prying tool that should work fine, if all you have is metal, you can use that, just make sure to be careful.

Get your tool under the mainboard, and lift it up gently, moving around the mainboard, as they un-clip, then when all the tabs are un-clipped, you can take the mainboard out with your hand, next flick the locks on the mainboard for the camera's and remove them from the mainboard, you'll want to add these to your new mainboard before you put the new mainboard in the case.

Putting it back together

Grab your new mainboard, and open up all the slots for input, slide in the ribbon cables for the camera's, and clip them back in, now you can put the mainboard back in, make sure the mainboard has the kill switches facing you, put the mainboard in the phone, but be careful not have the cables above the mainboard, so you don't squish or break any when you're pushing the new mainboard down, as long as the cables are above the mainboard, push down until you hear the tabs click and hold the mainboard back in place, you may need to wiggle it around a little.

Put the rest of the ribbon cables back in and close the tabs, this may be a bit finicky, but if you give it a few goes you'll be okay, the hardest one to put back in, is the antenna cable, you may want to pull the cable out of the phone a bit to give yourself more wiggle room to get it hooked up, its also recommended that you use something like a flat ended screwdriver to push the cable back in, then make sure you push the cable back into the space its allotted.

After all the cables are in, plug in your SDcard with JumpDrive installed, and battery, its best to test the device before you put it back together again, if the screen turns on and JumpDrive starts, you haven't destroyed your device.

Remove the battery again and put the inner frame back on, screw the frame back into place, and put your battery back in.

You also get a thermal pad with your mainboard, that sticks onto the inner part of the back cover so you may want to add that now, then put your back on.

Ubuntu Touch Time

Download the latest version of Ubuntu Touch from the official Jenkins, if you use etcher you can use the compressed file to flash, however all this does is extract the file somewhere else and then pushes it to your phone, this is usually okay if the file that's being extracted isn't to big, but the file that comes out the other end is about 13GB's so I recommend extracting it somewhere locally, that way if something goes wrong, you know where, you know why, and you know what to do about it, also extracting large archives like that can take a tole on a computer, especially if your computer is lower end, so don't do much while extracting, unless you have a powerful computer.

After the img is extracted, turn your phone on and plug it in, then flash with your favourite flashing tool, however, be aware that with JumpDrive gives you an option to write to the eMMC or the SDcard, make sure you get the right partition (eMMC if you want it internally), for me the eMMC drive was located at /dev/sde.

Wait for that to finish flashing, turn off your phone, open your phone back up for the last time, remove your JumpDrive Sd card and insert your normal one and you Sim card if you so wish, and turn the phone back on for its first boot.

It takes a bit longer to boot on first run, but after its finished booting, go through the setup wizard, and check that everything else is working, such as sound, Bluetooth, cameras, etc, to make sure that you've connected everything correctly before you start bringing all your stuff over.

Migration

To migrate your stuff we turn off the phone, and turn it back on holding volume down, then remember where your data should be stored on the phone? userdata/user-data/phablet, so copy and paste your back up folders into that folder.

You may run into permission errors, and if so you can use

sudo chmod 772 * -R

If you're not comfortable with the command line than I don't recommend restoring your data like this, and rather just reinstall everything and use your sd card to transfer your files in your standard directories back.

after you've copied everything you want back, reboot into Ubuntu Touch, open the terminal and use

ls -laR

Check and see who the owner and group the files belong to, if they belong to "system" then Ubuntu Touch wont be able to use them, the easiest way to fix the owner issue, is by using this command

sudo chown phablet:phablet -R

This changes every file from your home directory to be owned by phablet, and this will fix a lot of issues you have later when reinstalling apps, or trying to look at your images in the gallery app.

install UB tweak tool, and then install your other apps, if any app just shows a blank page, or doesn't work after the update, you're going to have to clear data, and start again with that app unfortunately.

Enjoy

Enjoy playing with your new 3GB version of the PinePhone!