Skip to content

Latest commit

 

History

History
255 lines (175 loc) · 10.2 KB

README-en.md

File metadata and controls

255 lines (175 loc) · 10.2 KB

Note: This is an automatically translated file. Original content from here:

This repository contains the necessary files to configure, build, and launch a Docker container, including docker-compose.yaml, Dockerfile, and scripts. Some environment variables are stored in a .env file, which must be created with the create-env.sh script so that some settings can be adopted by the host system. You also need a base Docker image that is automatically requested from Docker Hub. The use of this repository is intended to help create Docker containers that provide the necessary requirements to be able to build flash images and packages with the Yocto/OE build system.

1. Requirements

Tested under Linux Debian 11.x, Ubuntu 20.04, 22.04. But it should work on any current distribution that runs Docker.

Necessary:

  • Docker, Installation
  • Docker Compose >= v2.24.3, Installation
  • Git, installation via the package manager depending on the distribution

Optional:

Important! After you have installed Docker and want to run Docker as a non-root user, which is appropriate for our purposes, you should add yourself as a user to the "docker" group using this command:

sudo usermod -aG docker $USER

Then to apply the setting, either log out and log in again or restart!

2. Prepare

2.1. Clone repository and switch to the cloned repo

git clone https://github.com/tuxbox-neutrino/docker-buildenv.git && cd docker-buildenv

2.2. Configure environment variables

Run this script to create the necessary .env file:

./create-env.sh

The script gets some environment variables from the host system and puts them into an .env file so that the container is configured to suit your host system. As a rule, that should be enough. Adjustments are usually not required. However, if this does not cover your requirements, you can adapt this generated .env file. However, you should not run the script again, otherwise the .env file will be overwritten again. It is therefore advisable to either rename this customized .env file and rename it accordingly in the docker-compose.yml file, or preferably to use another one in this form as a parameter when running docker-compose - -env-file <my .env file>passed todocker-compose`.

2.3 Volumes

The container uses Docker Volumes to store persistent data, which allows access to specific files and directories permanently in the container. In the standard configuration, these volumes are in principle integrated to suit the environment of your host system and mounted when the container is started, so that ideally you do not have to change anything in the volume configuration. If you want to make changes to this, you can find the configuration of the volumes in docker-compose.yml. Note that these settings are normally aligned with the paths as preconfigured for the Yocto/OE build environment using the init script from the Buildenv repository. If adjustments are made to this, you should take this into account!

These paths are mounted as volumes in the container. You have normal access to it via your host:

/home
  └──<$USER>
      ├── tuxbox
      │ ├── .config
      │ ├── .data
      │ ├── am
      │ └── buildenv
      ├── Archives
      ├── am
      ├── sources
      ├── sstate cache

2.4 Configure ports

The container provides some access via certain network ports. This allows access to the build results via a web browser and access to the container via ssh.

2.4.1 Web access

By default, the container is configured to listen on port 80. Your host is mapped to the container's built-in web server (lighttpd) via port 8080:

  • Port: 8080 (host) -> 80 (container)

This enables access via web server to the generated images and packages (ipk's). Set-top boxes can therefore access updates directly from your home network, for example. If port 8080 on your host system is already occupied, you can either adjust these settings in the docker-compose.yml file or specify them when starting the container. This could look like this if you map to port 8081:

  • 8081:80

Settings on the web server can be made in the responsible lighttpd configuration file, which is available in the corresponding volume:

 ~/tuxbox
   └──.config
      └── lighttpd
          └── lighttpd.conf

dir-listing is activated in lighttpd.conf, so that you can get by without additional content.

~/tuxbox/config/lighttpd$ cat lighttpd.conf
...
#server.compat-module-load = "disable"
server.modules += (
      "mod_dirlisting",
      "mod_staticfile",
)
dir-listing.activate = "enable"

2.4.2 SSH

Usually you access the container directly via docker exec. Since Git is already part of the container, an ssh server is also provided. By default, the ssh server is configured like this:

  • Port: 222 (host) -> 22 (container)
  • Password: = Username (as set in .env)

If port 222 is already occupied on your host system, you can adjust these settings in the docker-compose.yml file, just like with the web server, or specify them when starting the container.

Login from the host system itself:

ssh $USER@localhost -p 222

Log in from another computer:

ssh <user>@<IP or hostname of the computer on which the container is running> -p 222

3. Build containers

3.1 Example 1

Run docker-compose wrapper:

./docker-compose build

Note: The preceding ./ must be taken into account here since the wrapper script is in the repo. The wrapper script calls docker-compose as intended, but after automatically creating an .env file as described in Step 2.2! This wrapper script takes all parameters common to docker-compose. It only serves to reduce the effort required to enter commands to create the environment variables, which are provided via the generated .env file.

3.2 Example 2

Run docker-compose: with different .env file

Note: Hm repository includes an .env.sample as an example. However, if desired, this must be adjusted and explicitly passed to docker-compose when creating the container.

docker-compose --env-file <path to other .env file> build

4. Start container

docker-compose up -d

5. Stop containers

docker-compose down

6. Using the container

6.1. log in

You should know the name or container ID to log in. Run docker ps to see which containers are currently available:

docker ps
CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES
9d6e0d280a9e tuxbox-build:latest "/usr/local/bin/star…" 41 minutes ago Up 41 minutes 0.0.0.0:8080->80/tcp tuxbox-build

For example, log in to the container with the Container ID 9d6e0d280a9e or the Container Name like this:

docker exec -it --user $USER tuxbox-build bash

or:

docker exec -it --user $USER <CONTAINER ID> bash

You should see something like this prompt:

~/tuxbox/buildenv$

First you should make sure that the init script is up to date. Therefore, carry out an update:

~/tuxbox/buildenv$ git pull -r origin master

From now on you can use the build environment with the container.

6.2. Use build environment

After logging into the container, you are already in the buildenv directory, where the init script is located. Now you can continue as described here.

The images and packages produced by the build system are made available via persistent volumes within your host home directory. By default, this location is intended for this:

/home
 └──<$USER>
     ├── tuxbox
     : ├── buildenv
         : ├── dist
             :

Note: If you have set up your volumes differently, this may of course differ.

The container provides a web server and can be accessed locally and on the LAN via port 8080 by default:

or on the LAN

7. Update containers

As stated in Step 2.1, the repository that contains the recipe for the container can be updated regularly. To do this, go to the repository and run this command:

 ~/docker-buildenv$ git pull -r origin master

Then have the container created as described here.

8. Support

For further questions, problems or support, open an Issue in GitHub or report in the [Forum](https://forum.tuxbox-neutrino.org /forum/viewforum.php?f=77).