Readme (#148)

Updated README.md and added config-create-default command.

README.md

@@ -12,15 +12,19 @@ You will get a help text with all management commands.
 
 ## How to start the full system
 
-You can start OpenSlides with Docker Compose as follows:
+You can start OpenSlides with Docker Compose. It is also possible to use Docker
+Swarm or other container orchestration systems instead of Docker Compose for
+bigger setups, but this is not described here.
 
-Be sure you have Docker and Docker Compose installed and Docker daemon is
-running. Check if you have to run docker as local user or as root.
+So for now let's use Docker Compose. Be sure you have Docker and Docker Compose
+installed and the Docker daemon is running. Check if you have to run docker as
+local user or as root.
 
     $ docker info
 
-Go to a nice place in your filesystem and download the manage tool `openslides`.
-To setup the instance in this directory run:
+Go to a nice place in your filesystem and build or
+[download](https://github.com/OpenSlides/openslides-manage-service/releases) the
+manage tool `openslides`. To setup the instance in this directory run:
 
     $ ./openslides setup .
 
@@ -61,55 +65,75 @@ To remove all containers run:
 
     $ docker-compose rm
 
-It is also possible to use Docker Swarm instead of Docker Compose for bigger
-setups. Let us know if this is interesting for you.
+To remove the database you have to remove the content of the `db-data`
+directory.
 
 
-## Configuration of the generated YAML file
+## Configuration of the generated Docker Compose YAML file
 
-The setup command generates a YAML file (default filename: `docker-compose.yml`)
-with the container configuration for all services. This step can be configured
-with a YAML formated config file. E. g. to get a customized YAML file run:
+The `setup` command generates a Docker Compose YAML file (default filename:
+`docker-compose.yml`) with the container configuration for all services. This
+step can be configured with a (second) YAML formated setup configuration file.
+
+E. g. create a file `my-config.yml` with the following content:
+
+    ---
+    port: 9000
+
+After you have such a file remove your Docker Compose YAML file and rerun the
+`setup` command:
 
     $ ./openslides setup --config my-config.yml .
 
-To rebuild the YAML file without resetting the whole directory (including
-secrets) run:
+This way you get a Docker Compose YAML file which let OpenSlides listen on the
+configured custom port.
+
+You may also use  the `--force` flag in some cases which also resets secrets and
+much more. To rebuild the Docker Compose YAML file without resetting the whole
+directory (including secrets) use the `config` command instead of the `setup`
+command. E. g. run:
 
     $ ./openslides config --config my-config.yml .
 
-See the [default config](pkg/config/default-config.yml) for syntax and defaults
-of this configuration YAML file.
+This command will just rebuild your Docker Compose YAML file.
+
+To get the [default config](pkg/config/default-config.yml) run:
+
+    $ ./openslides config-create-default .
+
+So you get a file where you can see syntax and defaults and might be able to
+customize the steps above.
 
 
 ## SSL encryption
 
 The manage tool provides settable options for using SSL encryption, which can be
-set in a `config.yml` file.
+set in the [custom YAML configuration
+file](#Configuration-of-the-generated-Docker-Compose-YAML-file).
 
-If you do not use a custom `config.yml` the setup command generates a
-self-signed certificate by default.
+If you do not use any customization, the `setup` command generates a self-signed
+certificate by default.
 
 If you want to use any other certificate you posses, just replace `cert_crt` and
-`cert_key` files in the `secrets` directory before starting docker.
+`cert_key` files in the `secrets` directory before starting Docker.
 
-If you want to disable SSL encryption, because you use OpenSlides behind your own
-proxy that provides SSL encryption, just  add the following line to your
-`config.yml`.
+If you want to disable SSL encryption, because you use OpenSlides behind your
+own proxy that provides SSL encryption, just  add the following line to your
+YAML configuration file.
 
     enableLocalHTTPS: false
 
 If you run OpenSlides behind a publicly accessible domain, you can use caddys
-integrated certificate retrieval. Add the following lines to your `config.yml`
-before running the setup command:
+integrated certificate retrieval. Add the following lines to your YAML
+configuration file before running the setup command:
 
     enableAutoHTTPS: true
     defaultEnvironment:
       EXTERNAL_ADDRESS: openslides.example.com
       # Use letsencrypt staging environment for testing
       # ACME_ENDPOINT: https://acme-staging-v02.api.letsencrypt.org/directory
 
-See [the proxy service](https://github.com/OpenSlides/OpenSlides/blob/master/proxy) for
+See [the proxy service](https://github.com/OpenSlides/OpenSlides/blob/main/proxy) for
 details on provided methods for HTTPS activation.
 
 
@@ -132,20 +156,27 @@ The server can be build with:
 
     $ go build ./cmd/server
 
-To compile changed `.proto` files, run `protoc`:
+To compile changed `.proto` files, install the [Protocol Buffer
+Compiler](https://grpc.io/docs/protoc-installation/) and its [Go
+plugins](https://grpc.io/docs/languages/go/quickstart/). Then run `protoc`:
 
     $ make protoc
 
 
-## Docker
+## Using Docker images
 
 You can build the following Docker images.
 
 To build the manage service server use:
 
     $ docker build .
 
-To build the client e. g. for use as one shot container with customized command
+To build the tool e. g. for use as one shot container with customized command
 use:
 
     $ docker build --target client .
+
+Finally you can use Docker to build the tool even without having Go installed.
+Just run:
+
+    $ make openslides

pkg/client/client.go

@@ -55,6 +55,7 @@ func RootCmd() *cobra.Command {
 	cmd.AddCommand(
 		setup.Cmd(),
 		config.Cmd(),
+		config.CmdCreateDefault(),
 		unaryConnection(initialdata.Cmd),
 		unaryConnection(setpassword.Cmd),
 		unaryConnection(createuser.Cmd),

pkg/client/client_test.go

@@ -6,6 +6,7 @@ import (
 	"testing"
 
 	"github.com/OpenSlides/openslides-manage-service/pkg/client"
+	"github.com/OpenSlides/openslides-manage-service/pkg/config"
 	"github.com/OpenSlides/openslides-manage-service/pkg/initialdata"
 	"github.com/OpenSlides/openslides-manage-service/pkg/setpassword"
 	"github.com/OpenSlides/openslides-manage-service/pkg/setup"
@@ -37,6 +38,18 @@ func TestCmdHelpTexts(t *testing.T) {
 			outputStartsWith: []byte(setup.SetupHelp),
 		},
 
+		{
+			name:             "config command",
+			input:            []string{"config", "--help"},
+			outputStartsWith: []byte(config.ConfigHelp),
+		},
+
+		{
+			name:             "config create default",
+			input:            []string{"config-create-default", "--help"},
+			outputStartsWith: []byte(config.ConfigCreateDefaultHelp),
+		},
+
 		{
 			name:             "initial-data command",
 			input:            []string{"initial-data", "--help"},

pkg/config/config.go

@@ -24,13 +24,19 @@ var defaultConfig []byte
 
 const (
 	// ConfigHelp contains the short help text for the command.
-	ConfigHelp = "Rebuilds the YAML file for using Docker Compose or Docker Swarm"
+	ConfigHelp = "(Re)creates the container configuration YAML file for using Docker Compose or Docker Swarm"
 
 	// ConfigHelpExtra contains the long help text for the command without the headline.
-	ConfigHelpExtra = `This command (re)creates a YAML file in the given directory.`
+	ConfigHelpExtra = `This command (re)creates the container configuration YAML file in the given directory.`
+
+	// ConfigCreateDefaultHelp contains the short help text for the command.
+	ConfigCreateDefaultHelp = "(Re)creates the default setup configuration YAML file"
+
+	// ConfigCreateDefaultHelpExtra contains the long help text for the command without the headline.
+	ConfigCreateDefaultHelpExtra = `This command (re)creates the default setup configuration YAML file in the given directory.`
 )
 
-// Cmd returns the setup subcommand.
+// Cmd returns the config subcommand.
 func Cmd() *cobra.Command {
 	cmd := &cobra.Command{
 		Use:   "config directory",
@@ -260,3 +266,40 @@ func NewYmlConfig(configFiles [][]byte) (*YmlConfig, error) {
 
 	return config, nil
 }
+
+// CmdCreateDefault returns the config-create-default subcommand.
+func CmdCreateDefault() *cobra.Command {
+	cmd := &cobra.Command{
+		Use:   "config-create-default",
+		Short: ConfigCreateDefaultHelp,
+		Long:  ConfigCreateDefaultHelp + "\n\n" + ConfigCreateDefaultHelpExtra,
+		Args:  cobra.ExactArgs(1),
+	}
+
+	name := cmd.Flags().StringP("file", "f", "config.yml", "name of the created file")
+
+	cmd.RunE = func(cmd *cobra.Command, args []string) error {
+		dir := args[0]
+
+		if err := configCreateDefault(dir, *name); err != nil {
+			return fmt.Errorf("running ConfigCreateDefault(): %w", err)
+		}
+
+		return nil
+	}
+	return cmd
+}
+
+// configCreateDefault creates the default setup configuration YAML file.
+func configCreateDefault(dir, name string) error {
+	// Create directory
+	if err := os.MkdirAll(dir, os.ModePerm); err != nil {
+		return fmt.Errorf("creating directory at %q: %w", dir, err)
+	}
+
+	// Create file
+	if err := shared.CreateFile(dir, true, name, defaultConfig); err != nil {
+		return fmt.Errorf("creating config default file at %q: %w", dir, err)
+	}
+	return nil
+}

pkg/config/config_test.go

@@ -30,6 +30,24 @@ func TestCmd(t *testing.T) {
 		}
 	})
 
+	t.Run("executing setup.CmdCreateDefault() with existing directory", func(t *testing.T) {
+		testDir, err := os.MkdirTemp("", "openslides-manage-service-")
+		if err != nil {
+			t.Fatalf("generating temporary directory failed: %v", err)
+		}
+		defer os.RemoveAll(testDir)
+
+		cmd := config.CmdCreateDefault()
+		cmd.SetArgs([]string{testDir})
+		if err := cmd.Execute(); err != nil {
+			t.Fatalf("executing config-create-default subcommand: %v", err)
+		}
+
+		p := path.Join(testDir, "config.yml")
+		if _, err := os.Stat(p); errors.Is(err, os.ErrNotExist) {
+			t.Fatalf("file %q does not exist, expected existance", p)
+		}
+	})
 }
 
 func TestConfigWithCustomConfig(t *testing.T) {

pkg/createuser/createuser.go

@@ -17,7 +17,7 @@ import (
 
 const (
 	// CreateUserHelp contains the short help text for the command.
-	CreateUserHelp = "Creates a new user"
+	CreateUserHelp = "Creates a new user in OpenSlides"
 
 	// CreateUserHelpExtra contains the long help text for the command without
 	// the headline.

pkg/initialdata/initialdata.go

@@ -23,8 +23,9 @@ const (
 
 	// InitialDataHelpExtra contains the long help text for the command without
 	// the headline.
-	InitialDataHelpExtra = `This command also sets password of user 1 to the value of the docker
-secret "superadmin" which is "superadmin" by default. It does nothing if the datastore is not empty.`
+	InitialDataHelpExtra = `This command also sets password of user 1 to the value of the docker secret
+"superadmin" which is "superadmin" by default. It returns an error if the
+datastore is not empty.`
 )
 
 // Cmd returns the initial-data subcommand.

pkg/setpassword/setpassword.go

@@ -13,7 +13,7 @@ import (
 
 const (
 	// SetPasswordHelp contains the short help text for the command.
-	SetPasswordHelp = "Sets the password of an user"
+	SetPasswordHelp = "Sets the password of an user in OpenSlides"
 
 	// SetPasswordHelpExtra contains the long help text for the command without
 	// the headline.
@@ -29,7 +29,7 @@ func Cmd(cmd *cobra.Command, cfg connection.Params) *cobra.Command {
 
 	userID := cmd.Flags().Int64P("user_id", "u", 0, "ID of the user account")
 	cmd.MarkFlagRequired("user_id")
-	password := cmd.Flags().StringP("password", "p", "", "New password of the user")
+	password := cmd.Flags().StringP("password", "p", "", "new password of the user")
 	cmd.MarkFlagRequired("password")
 
 	cmd.RunE = func(cmd *cobra.Command, args []string) error {

pkg/setup/setup.go

@@ -30,12 +30,12 @@ const (
 
 const (
 	// SetupHelp contains the short help text for the command.
-	SetupHelp = "Builds the required files for using Docker Compose or Docker Swarm"
+	SetupHelp = "Creates the required files for using Docker Compose or Docker Swarm"
 
 	// SetupHelpExtra contains the long help text for the command without the headline.
-	SetupHelpExtra = `This command creates a YAML file. It also creates the required secrets and
-directories for volumes containing persistent database and SSL certs. Everything
-is created in the given directory.`
+	SetupHelpExtra = `This command creates a container configuration YAML file. It also creates the
+required secrets and directories for volumes containing persistent database and
+SSL certs. Everything is created in the given directory.`
 
 	// SecretsDirName is the name of the directory for Docker Secrets.
 	SecretsDirName = "secrets"

pkg/tunnel/tunnel.go

@@ -19,7 +19,7 @@ import (
 
 const (
 	// TunnelHelp contains the short help text for the command.
-	TunnelHelp = "Creates tcp tunnels to the OpenSlides network"
+	TunnelHelp = "Creates TCP tunnels to the OpenSlides network"
 
 	// TunnelHelpExtra contains the long help text for the command without the headline.
 	TunnelHelpExtra = `Opens local ports to all services and creates